diff options
| author | Ralph Amissah <ralph@amissah.com> | 2012-11-18 21:50:04 -0500 |
|---|---|---|
| committer | Ralph Amissah <ralph@amissah.com> | 2012-12-12 09:44:37 -0500 |
| commit | eae9bb93fdd2e677c8882bcc96d42b804ac2bafe (patch) | |
| tree | 5b5b33598ba30847c07888f6eb8cc644a8133876 /data/doc/sisu/html/sisu4.1.html | |
| parent | v4: vim syntax, sisu.vim, make, new headers (diff) | |
v4: documentation; markup samples & help
Diffstat (limited to 'data/doc/sisu/html/sisu4.1.html')
| -rw-r--r-- | data/doc/sisu/html/sisu4.1.html | 3693 |
1 files changed, 3693 insertions, 0 deletions
diff --git a/data/doc/sisu/html/sisu4.1.html b/data/doc/sisu/html/sisu4.1.html new file mode 100644 index 00000000..345e574b --- /dev/null +++ b/data/doc/sisu/html/sisu4.1.html @@ -0,0 +1,3693 @@ +<!-- manual page source format generated by PolyglotMan v3.2, --> +<!-- available at http://polyglotman.sourceforge.net/ --> + +<html> +<head> +<title>"sisu"("1") manual page</title> +</head> +<body bgcolor='white'> +<a href='#toc'>Table of Contents</a><p> +<br> + +<h2><a name='sect0' href='#toc0'>Name</a></h2> +<br> +sisu - documents: markup, structuring, publishing in multiple standard formats, +and search <br> + +<h2><a name='sect1' href='#toc1'>Synopsis</a></h2> +<br> +sisu [-short-options|--long-options] [filename/wildcard] +<p> <br> +sisu [-abCcDdeFGghIikLMmNnoPpQqRrSsTtUuVvWwXxYyZ_0-9] [filename/wildcard] + +<p> <br> +sisu --txt --html --epub --odt --pdf --wordmap --sqlite --manpage --texinfo --sisupod --source +--qrcode [filename/wildcard] +<p> <br> +sisu [-Ddcv] [instruction] [filename/wildcard] +<p> <br> +sisu --pg (--createdb|update [filename/wildcard]|--dropall) +<p> <br> +sisu [operations] +<p> <br> +sisu [-CcFLSVvW] +<p> <br> +sisu (--configure|--webrick|--sample-search-form) +<h2><a name='sect2' href='#toc2'>Sisu - Manual,</a></h2> +RALPH AMISSAH <br> + +<p> +<h2><a name='sect3' href='#toc3'>What is Sisu?</a></h2> +<br> + +<p> +<h2><a name='sect4' href='#toc4'>Introduction - What is Sisu?</a></h2> +<br> + +<p> <br> +<b>SiSU</b> 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. +<p> <br> +<b>SiSU</b> is developed under an open source, software libre license ( <i>GPLv3</i> +). 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. + +<p> <br> +<b>SiSU</b> both defines a markup syntax and provides an engine that produces +open standards format outputs from documents prepared with <b>SiSU</b> 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 <b>SiSU</b> markup is more sparse than html and +outputs which include <i>HTML,</i> <i>EPUB,</i> <i>ODT</i> (Open Document Format text), <i>LaTeX,</i> +landscape and portrait <i>PDF,</i> all of which can be added to and updated. <b>SiSU</b> +is also able to populate <i>SQL</i> type databases at an object level, which means +that searches can be made with that degree of granularity. +<p> <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</b> markup applied to a document, <b>SiSU</b> custom builds (to +take advantage of the strengths of different ways of representing documents) +various standard open output formats including plain text, <i>HTML,</i> <i>XHTML,</i> +<i>XML,</i> <i>EPUB,</i> <i>ODT,</i> <i>LaTeX</i> or <i>PDF</i> files, and populate an <i>SQL</i> 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. +<p> <br> +In preparing a <b>SiSU</b> 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. +<p> <br> +<b>SiSU</b> 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</b> 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</b> is able +to take advantage of. +<p> <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</b> provides the flexibility of producing documents in multiple non-proprietary +open formats including <i>HTML,</i> <i>EPUB,</i> [^5] <i>ODT,</i> [^6] <i>PDF</i> [^7] <i>ODF,</i> [^8]. Whilst +<b>SiSU</b> 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</b> +can be migrated to other document formats. Further security is provided +by the fact that the software itself, <b>SiSU</b> is available under <i>GPLv3</i> 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</b> 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</i> was introduced in 2009; and allows the technical +representations existing output to be updated ( <i>HTML</i> has evolved and the +related module has been updated repeatedly over the years, presumably when +the World Wide Web Consortium (w3c) finalises <i>HTML</i> 5 which is currently +under development, the <i>HTML</i> module will again be updated allowing all existing +documents to be regenerated as <i>HTML</i> 5). +<p> <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. +<p> <br> +<b>SiSU</b> 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</b> +offers great possibilities. +<p> <br> +<b>SiSU</b> is primarily for published works, which can take advantage of the +citation system to reliably reference its documents. <b>SiSU</b> 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.</b> +<p> <br> +<<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +<p> <br> +<<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> +<p> +<h2><a name='sect5' href='#toc5'>Commands Summary</a></h2> +<br> + +<p> +<h2><a name='sect6' href='#toc6'>Description</a></h2> + +<p> <br> +<b>SiSU</b> is a document publishing system, that from a simple single marked-up +document, produces multiple output formats including: <i>plaintext,</i> <i>HTML,</i> +<i>XHTML,</i> <i>XML,</i> <i>EPUB,</i> <i>ODT</i> ( <i>OpenDocument</i> ( <i>ODF</i> ) text), <i>LaTeX,</i> <i>PDF,</i> info, and +<i>SQL</i> ( <i>PostgreSQL</i> and <i>SQLite</i> ) , which share text object numbers ("object +citation numbering") and the same document structure information. For more +see: <<a href='http://sisudoc.org'>http://sisudoc.org</a> +> or <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> +<p> +<h2><a name='sect7' href='#toc7'>Document Processing +Command Flags</a></h2> + +<p> +<dl> + +<dt><b>-a [filename/wildcard]</b> </dt> +<dd>produces <i>plaintext</i> with Unix linefeeds +and without markup, (object numbers are omitted), has footnotes at end +of each paragraph that contains them [ -A for 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) +<p> </dd> + +<dt><b>-b [filename/wildcard]</b> </dt> +<dd>see --xhtml +<p> </dd> + +<dt><b>--by-*</b> </dt> +<dd>see --output-by-* +<p> </dd> + +<dt><b>-C</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>-CC</b> </dt> +<dd>see --configure +<p> </dd> + +<dt><b>-c [filename/wildcard]</b> </dt> +<dd>see --color-toggle +<p> </dd> + +<dt><b>--color-toggle +[filename/wildcard]</b> </dt> +<dd>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 + +<p>- +<p>c +<p> </dd> + +<dt><b>--configure</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>--concordance +[filename/wildcard]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>-D [instruction] [filename]</b> </dt> +<dd>see --pg +<p> </dd> + +<dt><b>-d [--db-[database type + (sqlite|pg)]] --[instruction] [filename]</b> </dt> +<dd>see --sqlite +<p> </dd> + +<dt><b>--dal [filename/wildcard/url]</b> +</dt> +<dd>assumed for most other flags, creates new intermediate files for processing +(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. + +<p>Alias -m +<p> </dd> + +<dt><b>--delete [filename/wildcard]</b> </dt> +<dd>see --zap +<p> </dd> + +<dt><b>--dump[=directory_path] [filename/wildcard]</b> +</dt> +<dd>places output in directory specified, if none is specified in the current +directory (pwd). Compare --redirect +<p> </dd> + +<dt><b>-e [filename/wildcard]</b> </dt> +<dd>see --epub +<p> </dd> + +<dt><b>--epub +[filename/wildcard]</b> </dt> +<dd>produces an epub document, [sisu version >=2 ] (filename.epub). + +<p>Alias -e +<p> </dd> + +<dt><b>--exc-*</b> </dt> +<dd>exclude output feature, overrides configuration settings +--exc- <i>ocn,</i> (exclude <i>object</i> citation numbering, (switches off <i>object</i> 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-* +<p> </dd> + +<dt><b>-F [--webserv=webrick]</b> </dt> +<dd>see --sample-search-form + +<p> </dd> + +<dt><b>-f [optional string part of filename]</b> </dt> +<dd>see --find +<p> </dd> + +<dt><b>--find [optional string part + of filename]</b> </dt> +<dd>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 +<p> </dd> + +<dt><b>-G [optional string part of filename]</b> </dt> +<dd>see --find +<p> </dd> + +<dt><b>-g [filename/wildcard]</b> +</dt> +<dd> +<p>see --git +<p> </dd> + +<dt><b>--git [filename/wildcard]</b> </dt> +<dd>produces or updates markup source file +structure in a git repo (experimental and subject to change). Alias -g +<p> </dd> + +<dt><b>--glob +[optional string part of filename]</b> </dt> +<dd>see --find +<p> </dd> + +<dt><b>-h [filename/wildcard]</b> </dt> +<dd>see + +<p>- +<p>- +<p>html +<p> </dd> + +<dt><b>--harvest *.ss[tm]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>--help [topic]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>--html [filename/wildcard]</b> </dt> +<dd>produces html output, segmented text +with table of contents (toc.html and index.html) and the document in a single +file (scroll.html). Alias -h +<p> </dd> + +<dt><b>-I [filename/wildcard]</b> </dt> +<dd>see --texinfo +<p> </dd> + +<dt><b>-i [filename/wildcard]</b> +</dt> +<dd> +<p>see --manpage +<p> </dd> + +<dt><b>--inc-*</b> </dt> +<dd>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-* +<p> </dd> + +<dt><b>-j [filename/wildcard]</b> +</dt> +<dd>copies images associated with a file for use by html, xhtml & xml outputs +(automatically invoked by --dump & redirect). +<p> </dd> + +<dt><b>--keep-processing-files [filename/wildcard/url]</b> +</dt> +<dd> +<p>see --maintenance +<p> </dd> + +<dt><b>-L</b> </dt> +<dd>prints license information. +<p> </dd> + +<dt><b>-M [filename/wildcard/url]</b> +</dt> +<dd> +<p>see --maintenance +<p> </dd> + +<dt><b>-m [filename/wildcard/url]</b> </dt> +<dd>see --dal (document abstraction +level/layer) +<p> </dd> + +<dt><b>--machine [filename/wildcard/url]</b> </dt> +<dd>see --dal (document abstraction +level/layer) +<p> </dd> + +<dt><b>--maintenance [filename/wildcard/url]</b> </dt> +<dd>maintenance mode, interim +processing files are preserved and their locations indicated. (also see +-V). Aliases -M and --keep-processing-files. +<p> </dd> + +<dt><b>--manpage [filename/wildcard]</b> </dt> +<dd>produces +man page of file, not suitable for all outputs. Alias -i +<p> </dd> + +<dt><b>-N [filename/wildcard/url]</b> +</dt> +<dd>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. +<p> </dd> + +<dt><b>-n +[filename/wildcard/url]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>--no-*</b> </dt> +<dd>see --exc-* + +<p> </dd> + +<dt><b>-o [filename/wildcard/url]</b> </dt> +<dd>see --odt +<p> </dd> + +<dt><b>--odf [filename/wildcard/url]</b> </dt> +<dd>see --odt + +<p> </dd> + +<dt><b>--odt [filename/wildcard/url]</b> </dt> +<dd>output basic document in opendocument file +format (opendocument.odt). Alias -o +<p> </dd> + +<dt><b>--output-by-*</b> </dt> +<dd>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> </dd> + +<dt><b>-P [language_directory/filename language_directory]</b> </dt> +<dd>see --po4a + +<p> </dd> + +<dt><b>-p [filename/wildcard]</b> </dt> +<dd>see --pdf +<p> </dd> + +<dt><b>--pdf [filename/wildcard]</b> </dt> +<dd>produces <i>LaTeX</i> +pdf (portrait.pdf & landscape.pdf). Default paper size is set in config file, +or document header, or provided with additional command line parameter, +e.g. --papersize-a4 preset sizes include: ’A4’, U.S. ’letter’ and ’legal’ and book sizes +’A5’ and ’B5’ (system defaults to A4). Alias -p +<p> </dd> + +<dt><b>--pg [instruction] [filename]</b> +</dt> +<dd>database <i>PostgreSQL</i> ( --pgsql may be used instead) possible instructions, +include: --createdb; --create; --dropall; --import [filename]; --update [filename]; +--remove [filename]; see database section below. Alias -D +<p> </dd> + +<dt><b>--po [language_directory/filename + language_directory]</b> </dt> +<dd>see --po4a +<p> </dd> + +<dt><b>--po4a [language_directory/filename language_directory]</b> +</dt> +<dd>produces .pot and po files for the file in the languages specified by the +language directory. <b>SiSU</b> 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 +<p> </dd> + +<dt><b>-Q [filename/wildcard]</b> +</dt> +<dd> +<p>see --qrcode +<p> </dd> + +<dt><b>-q [filename/wildcard]</b> </dt> +<dd>see --quiet +<p> </dd> + +<dt><b>--qrcode [filename/wildcard]</b> +</dt> +<dd>generate QR code image of metadata (used in manifest). v3 only. +<p> </dd> + +<dt><b>--quiet [filename/wildcard]</b> +</dt> +<dd>quiet less output to screen. +<p> </dd> + +<dt><b>-R [filename/wildcard]</b> </dt> +<dd>see --rsync +<p> </dd> + +<dt><b>-r [filename/wildcard]</b> +</dt> +<dd> +<p>see --scp +<p> </dd> + +<dt><b>--redirect[=directory_path] [filename/wildcard]</b> </dt> +<dd>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). Compare --dump +<p> </dd> + +<dt><b>--rsync [filename/wildcard]</b> +</dt> +<dd>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 + +<p>- +<p>R +<p> </dd> + +<dt><b>-S</b> </dt> +<dd>see --sisupod +<p> </dd> + +<dt><b>-S [filename/wildcard]</b> </dt> +<dd>see --sisupod +<p> </dd> + +<dt><b>-s [filename/wildcard]</b> +</dt> +<dd> +<p>see --source +<p> </dd> + +<dt><b>--sample-search-form [--webserv=webrick]</b> </dt> +<dd>generate examples of (naive) +cgi search form for <i>SQLite</i> and PgSQL depends on your already having used +sisu to populate an <i>SQLite</i> and/or PgSQL database, (the <i>SQLite</i> version scans +the output directories for existing sisu_sqlite databases, so it is first +necessary to create them, before generating the search form) see -d -D and +the database section below. If the optional parameter --webserv=webrick is +passed, the cgi examples created will be set up to use the default port +set for use by the webrick server, (otherwise the port is left blank and +the system setting used, usually 80). The samples are dumped in the present +work directory which must be writable, (with screen instructions given +that they be copied to the cgi-bin directory). Alias -F +<p> </dd> + +<dt><b>--scp [filename/wildcard]</b> +</dt> +<dd>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 +<p> </dd> + +<dt><b>--sqlite +--[instruction] [filename]</b> </dt> +<dd>database type set to <i>SQLite,</i> this produces one +of two possible databases, without additional database related instructions +it produces a discreet <i>SQLite</i> file for the document processed; with additional +instructions it produces a common <i>SQLite</i> 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 +<p> </dd> + +<dt><b>--sisupod</b> </dt> +<dd>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<br> + option is tested only with zsh). Alias -S +<p> </dd> + +<dt><b>--sisupod [filename/wildcard]</b> </dt> +<dd>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. <b>SiSU</b> 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 +<p> </dd> + +<dt><b>--source [filename/wildcard]</b> </dt> +<dd>copies sisu markup +file to output directory. Alias -s +<p> </dd> + +<dt><b>-T [filename/wildcard (*.termsheet.rb)]</b> +</dt> +<dd>standard form document builder, preprocessing feature +<p> </dd> + +<dt><b>-t [filename/wildcard]</b> +</dt> +<dd> +<p>see --txt +<p> </dd> + +<dt><b>--texinfo [filename/wildcard]</b> </dt> +<dd>produces texinfo and info file, (view +with pinfo). Alias -I +<p> </dd> + +<dt><b>--txt [filename/wildcard]</b> </dt> +<dd>produces <i>plaintext</i> with Unix +linefeeds and without markup, (object numbers are omitted), has footnotes +at end of each paragraph that contains them [ -A for 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 +<p> </dd> + +<dt><b>-U [filename/wildcard]</b> </dt> +<dd>see --urls +<p> </dd> + +<dt><b>-u [filename/wildcard]</b> +</dt> +<dd>provides url mapping of output files for the flags requested for processing, + +<p>also see -U +<p> </dd> + +<dt><b>--urls [filename/wildcard]</b> </dt> +<dd>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. + +<p>Alias -U +<p> </dd> + +<dt><b>-V</b> </dt> +<dd>on its own, provides <b>SiSU</b> version and environment information +(sisu --help env) +<p> </dd> + +<dt><b>-V [filename/wildcard]</b> </dt> +<dd>even more verbose than the -v flag. + +<p> </dd> + +<dt><b>-v</b> </dt> +<dd>on its own, provides <b>SiSU</b> version information +<p> </dd> + +<dt><b>-v [filename/wildcard]</b> +</dt> +<dd> +<p>see --verbose +<p> </dd> + +<dt><b>--v3 [filename/wildcard]</b> </dt> +<dd>invokes the sisu v3 document parser/generator. +You may run sisu3 instead. +<p> </dd> + +<dt><b>--v4 [filename/wildcard]</b> </dt> +<dd>invokes the sisu v4 document +parser/generator. This is the default and is normally omitted. +<p> </dd> + +<dt><b>--verbose [filename/wildcard]</b> +</dt> +<dd>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 +<p> </dd> + +<dt><b>-W</b> </dt> +<dd>see --webrick + +<p> </dd> + +<dt><b>-w [filename/wildcard]</b> </dt> +<dd>see --concordance +<p> </dd> + +<dt><b>--webrick</b> </dt> +<dd>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 also, note -F webrick ]. Alias -W +<p> </dd> + +<dt><b>--wordmap [filename/wildcard]</b> +</dt> +<dd> +<p>see --concordance +<p> </dd> + +<dt><b>--xhtml [filename/wildcard]</b> </dt> +<dd>produces xhtml/ <i>XML</i> output for +browser viewing (sax parsing). Alias -b +<p> </dd> + +<dt><b>--xml-dom [filename/wildcard]</b> </dt> +<dd>produces +<i>XML</i> output with deep document structure, in the nature of dom. Alias -X +<p> +</dd> + +<dt><b>--xml-sax [filename/wildcard]</b> </dt> +<dd>produces <i>XML</i> output shallow structure (sax parsing). + +<p>Alias -x +<p> </dd> + +<dt><b>-X [filename/wildcard]</b> </dt> +<dd>see --xml-dom +<p> </dd> + +<dt><b>-x [filename/wildcard]</b> </dt> +<dd>see --xml-sax + +<p> </dd> + +<dt><b>-Y [filename/wildcard]</b> </dt> +<dd>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]) +<p> </dd> + +<dt><b>-y [filename/wildcard]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>-Z [filename/wildcard]</b> </dt> +<dd>see + +<p>- +<p>- +<p>zap +<p> </dd> + +<dt><b>--zap [filename/wildcard]</b> </dt> +<dd>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. + +<p>Alias -Z +<p> </dd> +</dl> + +<h2><a name='sect8' href='#toc8'>Command Line Modifiers</a></h2> +<br> + +<p> +<dl> + +<dt><b>--no-</b> </dt> +<dd><i>ocn</i> [with --html --pdf or --epub] switches off <i>object</i> citation numbering. +Produce output without identifying numbers in margins of html or <i>LaTeX</i> +/pdf output. +<p> </dd> + +<dt><b>--no-annotate</b> </dt> +<dd>strips output text of editor endnotes[^*1] denoted + +<p>by asterisk or dagger/plus sign +<p> </dd> + +<dt><b>--no-asterisk</b> </dt> +<dd>strips output text of editor +endnotes[^*2] denoted by asterisk sign +<p> </dd> + +<dt><b>--no-dagger</b> </dt> +<dd>strips output text of editor +endnotes[^+1] denoted by dagger/plus sign +<p> </dd> +</dl> + +<h2><a name='sect9' href='#toc9'>Database Commands</a></h2> +<br> + +<p> <br> +<b>dbi - database interface</b> +<p> <br> +<b>-D or --pgsql</b> set for <i>PostgreSQL</i> <b>-d or --sqlite</b> default set for <i>SQLite</i> -d is modifiable +with --db=[database type (PgSQL or .I SQLite ) ] +<p> +<dl> + +<dt><b>--pg -v --createall</b> </dt> +<dd>initial step, +creates required relations (tables, indexes) in existing <i>PostgreSQL</i> database +(a database should be created manually and given the same name as working +directory, as requested) (rb.dbi) [ -dv --createall .I SQLite equivalent] it +may be necessary to run sisu -Dv --createdb initially NOTE: at the present +time for <i>PostgreSQL</i> it may be necessary to manually create the database. +The command would be working directory name (without path)]. Please use +only alphanumerics and underscores. +<p> </dd> + +<dt><b>--pg -v --import</b> </dt> +<dd>[filename/wildcard] imports +data specified to <i>PostgreSQL</i> db (rb.dbi) [ -dv --import .I SQLite equivalent] + +<p> </dd> + +<dt><b>--pg -v --update</b> </dt> +<dd>[filename/wildcard] updates/imports specified data to <i>PostgreSQL</i> +db (rb.dbi) [ -dv --update .I SQLite equivalent] +<p> </dd> + +<dt><b>--pg --remove</b> </dt> +<dd>[filename/wildcard] +removes specified data to <i>PostgreSQL</i> db (rb.dbi) [ -d --remove .I SQLite equivalent] + +<p> </dd> + +<dt><b>--pg --dropall</b> </dt> +<dd>kills data" and drops ( <i>PostgreSQL</i> or <i>SQLite</i> ) db, tables & +indexes [ -d --dropall .I SQLite equivalent] +<p> <br> +The -v is for verbose output. +<p> </dd> +</dl> + +<h2><a name='sect10' href='#toc10'>Shortcuts, Shorthand for Multiple Flags</a></h2> +<br> + +<p> +<dl> + +<dt><b>--update [filename/wildcard]</b> </dt> +<dd>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. +<p> </dd> + +<dt><b>-0 to -5 [filename or wildcard]</b> </dt> +<dd>Default +shorthand mappings (for v3, note that the defaults can be changed/configured +in the sisurc.yml file): +<p> </dd> + +<dt><b>-0</b> </dt> +<dd>-NQhewpotbxXyYv [this is the default action run + when no options are give, i.e. on ’sisu [filename]’] +<p> </dd> + +<dt><b>-1</b> </dt> +<dd>-Qhewpoty +<p> </dd> + +<dt><b>-2</b> </dt> +<dd>-NQhewpotbxXy + +<p> </dd> + +<dt><b>-3</b> </dt> +<dd>-NQhewpotbxXyY +<p> </dd> + +<dt><b>-4</b> </dt> +<dd>-NQhewpotbxXDyY --update +<p> </dd> + +<dt><b>-5</b> </dt> +<dd>-NQhewpotbxXDyYv --update +<p> <br> +add -v for verbose mode and -c to toggle color state, e.g. sisu -2vc [filename + or wildcard] +<p> <br> + +<p>consider -u for appended url info or -v for verbose output +<p> </dd> +</dl> + +<h2><a name='sect11' href='#toc11'>Command Line +with Flags - Batch Processing</a></h2> + +<p> <br> +In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst" +or "sisu -h *.{sst,ssm}" to produce html version of all documents. +<p> <br> +Running sisu (alone without any flags, filenames or wildcards) brings up +the interactive help, as does any sisu command that is not recognised. Enter +to escape. +<p> +<h2><a name='sect12' href='#toc12'>Help</a></h2> +<br> + +<p> +<h2><a name='sect13' href='#toc13'>Sisu Manual</a></h2> + +<p> <br> +The most up to date information on sisu should be contained in the sisu_manual, +available at: +<p> <br> + <<a href='http://sisudoc.org/sisu/sisu_manual/'>http://sisudoc.org/sisu/sisu_manual/</a> +><br> + +<p> <br> +The manual can be generated from source, found respectively, either within +the <b>SiSU</b> tarball or installed locally at: +<p> <br> + ./data/doc/sisu/markup-samples/sisu_manual<br> + +<p> <br> + /usr/share/doc/sisu/markup-samples/sisu_manual<br> + +<p> <br> +move to the respective directory and type e.g.: +<p> <br> + sisu sisu_manual.ssm<br> + +<p> +<h2><a name='sect14' href='#toc14'>Sisu Man Pages</a></h2> + +<p> <br> +If <b>SiSU</b> is installed on your system usual man commands should be available, +try: +<p> <br> + man sisu<br> + +<p> <br> +Most <b>SiSU</b> man pages are generated directly from sisu documents that are +used to prepare the sisu manual, the sources files for which are located +within the <b>SiSU</b> tarball at: +<p> <br> + ./data/doc/sisu/markup-samples/sisu_manual<br> + +<p> <br> +Once installed, directory equivalent to: +<p> <br> + /usr/share/doc/sisu/markup-samples/sisu_manual<br> + +<p> <br> +Available man pages are converted back to html using man2html: +<p> <br> + /usr/share/doc/sisu/html/<br> + +<p> <br> + ./data/doc/sisu/html<br> + +<p> <br> +An online version of the sisu man page is available here: +<p> <br> +* various sisu man pages <<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a> +> [^9] +<p> <br> +* sisu.1 <<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> +> [^10] +<p> +<h2><a name='sect15' href='#toc15'>Sisu Built-in Interactive +Help</a></h2> + +<p> <br> +This is particularly useful for getting the current sisu setup/environment +information: +<p> <br> + sisu --help<br> + +<p> <br> + sisu --help [subject]<br> + +<p> <br> + sisu --help commands<br> + +<p> <br> + sisu --help markup<br> + +<p> <br> + sisu --help env [for feedback on the way your system is <br> + setup with regard to sisu ]<br> + +<p> <br> + sisu -V [environment information, same as above command]<br> + +<p> <br> + sisu (on its own provides version and some help information)<br> + +<p> <br> +Apart from real-time information on your current configuration the <b>SiSU</b> +manual and man pages are likely to contain more up-to-date information than +the sisu interactive help (for example on commands and markup). +<p> <br> +NOTE: Running the command sisu (alone without any flags, filenames or wildcards) +brings up the interactive help, as does any sisu command that is not recognised. +Enter to escape. +<p> +<h2><a name='sect16' href='#toc16'>Introduction to Sisu Markup[^11]</a></h2> +<br> + +<p> +<h2><a name='sect17' href='#toc17'>Summary</a></h2> + +<p> <br> +<b>SiSU</b> source documents are <i>plaintext</i> ( <i>UTF-8</i> )[^12] files +<p> <br> +All paragraphs are separated by an empty line. +<p> <br> +Markup is comprised of: +<p> <br> +* at the top of a document, the document header made up of semantic meta-data +about the document and if desired additional processing instructions (such +an instruction to automatically number headings from a particular level +down) +<p> <br> +* followed by the prepared substantive text of which the most important +single characteristic is the markup of different heading levels, which +define the primary outline of the document structure. Markup of substantive +text includes: +<p> <br> + * heading levels defines document structure<br> + +<p> <br> + * text basic attributes, italics, bold etc.<br> + +<p> <br> + * grouped text (objects), which are to be treated differently, such as +code<br> + blocks or poems.<br> + +<p> <br> + * footnotes/endnotes<br> + +<p> <br> + * linked text and images<br> + +<p> <br> + * paragraph actions, such as indent, bulleted, numbered-lists, etc.<br> + +<p> <br> +Some interactive help on markup is available, by typing sisu and selecting + +<p>markup or sisu --help markup +<p> <br> +To check the markup in a file: +<p> <br> + sisu --identify [filename].sst<br> + +<p> <br> + +<p>For brief descriptive summary of markup history +<p> <br> + sisu --query-history<br> + +<p> <br> +or if for a particular version: +<p> <br> + sisu --query-0.38<br> + +<p> +<h2><a name='sect18' href='#toc18'>Markup Examples</a></h2> + +<p> +<h2><a name='sect19' href='#toc19'>Online</a></h2> + +<p> <br> +Online markup examples are available together with the respective outputs +produced from <<a href='http://www.jus.uio.no/sisu/SiSU/examples.html'>http://www.jus.uio.no/sisu/SiSU/examples.html</a> +> or from <<a href='http://www.jus.uio.no/sisu/sisu_examples/'>http://www.jus.uio.no/sisu/sisu_examples/</a> +> + +<p> <br> +There is of course this document, which provides a cursory overview of +sisu markup and the respective output produced: <<a href='http://www.jus.uio.no/sisu/sisu_markup/'>http://www.jus.uio.no/sisu/sisu_markup/</a> +> + +<p> <br> +an alternative presentation of markup syntax: /usr/share/doc/sisu/on_markup.txt.gz + +<p> +<h2><a name='sect20' href='#toc20'>Installed</a></h2> + +<p> <br> +With <b>SiSU</b> 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: + +<p>/usr/share/doc/sisu/markup-samples-non-free +<p> +<h2><a name='sect21' href='#toc21'>Markup of Headers</a></h2> +<br> + +<p> <br> +Headers contain either: semantic meta-data about a document, which can be +used by any output module of the program, or; processing instructions. +<p> +<br> +Note: the first line of a document may include information on the markup +version used in the form of a comment. Comments are a percentage mark at +the start of a paragraph (and as the first character in a line of text) +followed by a space and the comment: +<p> <br> +<pre>% this would be a comment +</pre> +<p> +<h2><a name='sect22' href='#toc22'>Sample Header</a></h2> + +<p> <br> +This current document is loaded by a master document that has a header +similar to this one: +<p> <br> +<pre>% SiSU master 2.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: +:type: information +: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 +</pre> +<p> +<h2><a name='sect23' href='#toc23'>Available Headers</a></h2> + +<p> <br> +Header tags appear at the beginning of a document and provide meta information +on the document (such as the <i>Dublin</i> 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: + +<p>All <i>Dublin</i> Core meta tags are available +<p> <br> +<b>@indentifier:</b> information or instructions +<p> <br> +where the "identifier" is a tag recognised by the program, and the "information" +or "instructions" belong to the tag/indentifier specified +<p> <br> +Note: a header where used should only be used once; all headers apart from +@title: are optional; the @structure: header is used to describe document +structure, and can be useful to know. +<p> <br> + +<p>This is a sample header +<p> <br> +<pre>% SiSU 2.0 [declared file-type identifier with markup version] +</pre> +<p> <br> +<pre>@title: [title text] [this header is the only one that is mandatory] + :subtitle: [subtitle if any] + :language: English +</pre> +<p> <br> +<pre>@creator: +:author: [Lastname, First names] +:illustrator: [Lastname, First names] +:translator: [Lastname, First names] +:prepared_by: [Lastname, First names] +</pre> +<p> <br> +<pre>@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] +</pre> +<p> <br> +<pre>@rights: +:copyright: Copyright (C) [Year and Holder] +:license: [Use License granted] +:text: [Year and Holder] +:translation: [Name, Year] +:illustrations: [Name, Year] +</pre> +<p> <br> +<pre>@classify: +:topic_register: SiSU:markup sample:book;book:novel:fantasy +:type: +:subject: +:description: +:keywords: +:abstract: +:loc: [Library of Congress classification] +:dewey: Dewey classification +</pre> +<p> <br> +<pre>@identify: +:isbn: [ISBN] +:oclc: +</pre> +<p> <br> +<pre>@links: { SiSU }http://www.sisudoc.org + { FSF }http://www.fsf.org +</pre> +<p> <br> +<pre>@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 +</pre> +<p> <br> +<pre>@original: +:language: [language] +</pre> +<p> <br> +<pre>@notes: +:comment: +:prefix: [prefix is placed just after table of contents] +</pre> +<p> +<h2><a name='sect24' href='#toc24'>Markup of Substantive Text</a></h2> +<br> + +<p> +<h2><a name='sect25' href='#toc25'>Heading Levels</a></h2> + +<p> <br> +Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section +headings, followed by other heading levels, and 1 -6 being headings followed +by substantive text or sub-headings. :A~ usually the title :A~? conditional +level 1 heading (used where a stand-alone document may be imported into +another) +<p> <br> +<b>:A~ [heading text]</b> 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 +<p> <br> +<b>:B~ [heading text]</b> Second level heading [this is a heading level divider] + +<p> <br> +<b>:C~ [heading text]</b> Third level heading [this is a heading level divider] + +<p> <br> +<b>1~ [heading text]</b> 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 + +<p> <br> +<b>2~ [heading text]</b> 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. +<p> <br> +<b>3~ [heading text]</b> 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 + +<p> <br> +<pre>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) +</pre> +<p> +<h2><a name='sect26' href='#toc26'>Font Attributes</a></h2> + +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>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}# +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +normal text, <b>emphasis,</b> <b>bold text</b> , <i>italics,</i> <i>underscore,</i> "citation", ^superscript^, +[subscript], ++inserted text++, --strikethrough--, monospace +<p> <br> + +<p>normal text +<p> <br> +<b>emphasis</b> [note: can be configured to be represented by bold, italics italics + or underscore] or underscore] +<p> <br> + +<p><b>bold text</b> +<p> <br> + +<p><i>italics</i> +<p> <br> + +<p><i>underscore</i> +<p> <br> +"citation" +<p> <br> +^superscript^ +<p> <br> +[subscript] +<p> <br> +++inserted text++ +<p> <br> +--strikethrough-- +<p> <br> + +<p>monospace +<p> +<h2><a name='sect27' href='#toc27'>Indentation and Bullets</a></h2> + +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>ordinary paragraph +_1 indent paragraph one step +_2 indent paragraph two steps +_9 indent paragraph nine steps +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> + +<p>ordinary paragraph +<p> <br> + indent paragraph one step<br> + +<p> <br> + indent paragraph two steps<br> + +<p> <br> + indent paragraph nine steps<br> + +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>_* bullet text +_1* bullet text, first indent +_2* bullet text, two step indent +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +* bullet text +<p> <br> + * bullet text, first indent<br> + +<p> <br> + * bullet text, two step indent<br> + +<p> <br> +Numbered List (not to be confused with headings/titles, (document structure)) + +<p> <br> +<b>markup example:</b> +<p> <br> +<pre># numbered list numbered list 1., 2., 3, etc. +_# numbered list numbered list indented a., b., c., d., etc. +</pre> +<p> +<h2><a name='sect28' href='#toc28'>Hanging Indents</a></h2> + +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>_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 +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> + first line no indent, rest of paragraph indented one step<br> + +<p> <br> +first line indented, rest of paragraph no indent +<p> <br> + +<p>in each case level may be 0-9 +<p> +<h2><a name='sect29' href='#toc29'>Footnotes / Endnotes</a></h2> + +<p> <br> +Footnotes and endnotes are marked up at the location where they would be +indicated within a text. They are automatically numbered. The output type + +<p>determines whether footnotes or endnotes will be produced +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>~{ a footnote or endnote }~ +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +[^13] +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>normal text~{ self contained endnote marker & endnote in one }~ continues +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +normal text[^14] continues +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>normal text ~{* unnumbered asterisk footnote/endnote, insert multiple asterisks +if required }~ continues +normal text ~{** another unnumbered asterisk footnote/endnote }~ continues +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +normal text [^*] continues +<p> <br> +normal text [^**] continues +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>normal text ~[* editors notes, numbered asterisk footnote/endnote series + ]~ continues +normal text ~[+ editors notes, numbered asterisk footnote/endnote series + ]~ continues +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +normal text [^*3] continues +<p> <br> +normal text [^+2] continues +<p> <br> +<b>Alternative endnote pair notation for footnotes/endnotes:</b> +<p> <br> +<pre>% note the endnote marker "~^" +normal text~^ continues +^~ endnote text following the paragraph in which the marker occurs +</pre> +<p> <br> + +<p>the standard and pair notation cannot be mixed in the same document +<p> +<h2><a name='sect30' href='#toc30'>Links</a></h2> + +<p> + +<h2><a name='sect31' href='#toc31'>Naked Urls Within Text, Dealing with Urls</a></h2> + +<p> <br> +urls found within text are marked up automatically. A url within text is +automatically hyperlinked to itself and by default decorated with angled +braces, unless they are contained within a code block (in which case they +are passed as normal text), or escaped by a preceding underscore (in which +case the decoration is omitted). +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>normal text http://www.sisudoc.org/ continues +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +normal text <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> continues +<p> <br> + +<p>An escaped url without decoration +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>normal text _http://www.sisudoc.org/ continues +deb _http://www.jus.uio.no/sisu/archive unstable main non-free +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +normal text <_<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> continues +<p> <br> +deb <_<a href='http://www.jus.uio.no/sisu/archive'>http://www.jus.uio.no/sisu/archive</a> +> unstable main non-free +<p> <br> +where a code block is used there is neither decoration nor hyperlinking, + +<p>code blocks are discussed later in this document +<p> <br> +<b>resulting output:</b> +<p> <br> +<pre>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 +</pre> +<p> +<h2><a name='sect32' href='#toc32'>Linking Text</a></h2> + +<p> <br> + +<p>To link text or an image to a url the markup is as follows +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>about { SiSU }http://url.org markup +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +aboutSiSU <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> markup +<p> <br> + +<p>A shortcut notation is available so the url link may also be provided automatically + +<p>as a footnote +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>about {~^ SiSU }http://url.org markup +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +aboutSiSU <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> [^15] markup +<p> <br> +Internal document links to a tagged location, including an <i>ocn</i> +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>about { text links }#link_text +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +about ⌠text links⌡⌈link_text⌋ +<p> <br> + +<p>Shared document collection link +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>about { SiSU book markup examples }:SiSU/examples.html +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +about ⌠ <b>SiSU</b> book markup examples⌡⌈:SiSU/examples.html⌋ +<p> +<h2><a name='sect33' href='#toc33'>Linking +Images</a></h2> + +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>{ tux.png 64x80 }image +% various url linked images +{tux.png 64x80 "a better way" }http://www.sisudoc.org/ +{GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian +and Ruby" }http://www.sisudoc.org/ +{~^ ruby_logo.png "Ruby" }http://www.ruby-lang.org/en/ +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +[ tux.png ] +<p> <br> +tux.png 64x80 "Gnu/Linux - a better way" <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +<p> <br> +GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian +and Ruby" <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +<p> <br> +ruby_logo.png 70x90 "Ruby" <<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a> +> [^16] +<p> <br> + +<p><b>linked url footnote shortcut</b> +<p> <br> +<pre>{~^ [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 +</pre> +<p> <br> +<pre>text marker *~name +</pre> +<p> <br> +note at a heading level the same is automatically achieved by providing +names to headings 1, 2 and 3 i.e. 2~[name] and 3~[name] or in the case of +auto-heading numbering, without further intervention. +<p> +<h2><a name='sect34' href='#toc34'>Link Shortcut for +Multiple Versions of a Sisu Document in the Same Directory</a></h2> +TREE +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>!_ /{"Viral Spiral"}/, David Bollier +{ "Viral Spiral", David Bollier [3sS]}viral_spiral.david_bollier.sst +</pre> +<p> <br> +<b></b> <i>Viral Spiral</i>, David Bollier +<p> "Viral Spiral", David Bollier <<a href='http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html'>http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html</a> +> + document manifest <<a href='http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html'>http://corundum/sisu_manual/en/manifest/viral_spiral.david_bollier.html</a> +><br> + ⌠html, segmented text⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a> +<br> + ⌠html, scroll, document in one⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a> +<br> + ⌠epub⌡「<a href='http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」'>http://corundum/sisu_manual/en/epub/viral_spiral.david_bollier.epub」</a> +<br> + ⌠pdf, landscape⌡「<a href='http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」'>http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」</a> +<br> + ⌠pdf, portrait⌡「<a href='http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」'>http://corundum/sisu_manual/en/pdf/viral_spiral.david_bollier.pdf」</a> +<br> + ⌠odf: odt, open document text⌡「<a href='http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」'>http://corundum/sisu_manual/en/odt/viral_spiral.david_bollier.odt」</a> +<br> + ⌠xhtml scroll⌡「<a href='http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」'>http://corundum/sisu_manual/en/xhtml/viral_spiral.david_bollier.xhtml」</a> +<br> + ⌠xml, sax⌡「<a href='http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」'>http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」</a> +<br> + ⌠xml, dom⌡「<a href='http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」'>http://corundum/sisu_manual/en/xml/viral_spiral.david_bollier.xml」</a> +<br> + ⌠concordance⌡「<a href='http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」'>http://corundum/sisu_manual/en/html/viral_spiral.david_bollier.html」</a> +<br> + ⌠dcc, document content certificate (digests)⌡「<a href='http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」'>http://corundum/sisu_manual/en/digest/viral_spiral.david_bollier.txt」</a> +<br> + ⌠markup source text⌡「<a href='http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」'>http://corundum/sisu_manual/en/src/viral_spiral.david_bollier.sst」</a> +<br> + ⌠markup source (zipped) pod⌡「<a href='http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」'>http://corundum/sisu_manual/en/pod/viral_spiral.david_bollier.sst.zip」</a> +<br> + +<p> +<h2><a name='sect35' href='#toc35'>Grouped Text</a></h2> + +<p> +<h2><a name='sect36' href='#toc36'>Tables</a></h2> + +<p> <br> + +<p>Tables may be prepared in two either of two forms +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>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 +</pre> +<p> <br> +<b>resulting output:</b> +<p> 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』 +<p> <br> + +<p>a second form may be easier to work with in cases where there is not much + +<p>information in each column +<p> <br> +<b>markup example:</b> [^18] +<p> <br> +<pre>!_ 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. +</pre> +<p> <br> +<b>resulting output:</b> +<p> <br> +<b>Table 3.1: Contributors to Wikipedia, January 2001 - June 2005</b> +<p> |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』 +<p> <br> +* Contributed at least ten times; ** at least 5 times in last month; *** +more than 100 times in last month. +<p> +<h2><a name='sect37' href='#toc37'>Poem</a></h2> + +<p> <br> +<b>basic markup:</b> +<p> <br> +<pre>poem{ + Your poem here +}poem +Each verse in a poem is given an object number. +</pre> +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>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 +</pre> +<p> <br> +<b>resulting output:</b> +<p> ‘Fury said to a<br> + mouse, That he<br> + met in the<br> + house,<br> + "Let us<br> + both go to<br> + law: I will<br> + prosecute<br> + YOU. --Come,<br> + I’ll take no<br> + denial; We<br> + must have a<br> + trial: For<br> + really this<br> + morning I’ve<br> + nothing<br> + to do."<br> + Said the<br> + mouse to the<br> + cur, "Such<br> + a trial,<br> + dear Sir,<br> + With<br> + no jury<br> + or judge,<br> + would be<br> + wasting<br> + our<br> + breath."<br> + "I’ll be<br> + judge, I’ll<br> + be jury,"<br> + Said<br> + cunning<br> + old Fury:<br> + "I’ll<br> + try the<br> + whole<br> + cause,<br> + and<br> + condemn<br> + you<br> + to<br> + death."’<br> + +<p> +<h2><a name='sect38' href='#toc38'>Group</a></h2> + +<p> <br> +<b>basic markup:</b> +<p> <br> +<pre>group{ + Your grouped text here +}group +A group is treated as an object and given a single object number. +</pre> +<p> <br> +<b>markup example:</b> +<p> <br> +<pre>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 +</pre> +<p> <br> +<b>resulting output:</b> +<p> ‘Fury said to a<br> + mouse, That he<br> + met in the<br> + house,<br> + "Let us<br> + both go to<br> + law: I will<br> + prosecute<br> + YOU. --Come,<br> + I’ll take no<br> + denial; We<br> + must have a<br> + trial: For<br> + really this<br> + morning I’ve<br> + nothing<br> + to do."<br> + Said the<br> + mouse to the<br> + cur, "Such<br> + a trial,<br> + dear Sir,<br> + With<br> + no jury<br> + or judge,<br> + would be<br> + wasting<br> + our<br> + breath."<br> + "I’ll be<br> + judge, I’ll<br> + be jury,"<br> + Said<br> + cunning<br> + old Fury:<br> + "I’ll<br> + try the<br> + whole<br> + cause,<br> + and<br> + condemn<br> + you<br> + to<br> + death."’<br> + +<p> +<h2><a name='sect39' href='#toc39'>Code</a></h2> + +<p> <br> +Code tags code{ ... }code (used as with other group tags described above) +are used to escape regular sisu markup, and have been used extensively +within this document to provide examples of <b>SiSU</b> markup. You cannot however +use code tags to escape code tags. They are however used in the same way +as group or poem tags. +<p> <br> +A code-block is treated as an object and given a single object number. [an +option to number each line of code may be considered at some later time] + +<p> <br> +<b>use of code tags instead of poem compared, resulting output:</b> +<p> <br> +<pre> ‘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."’ +</pre> +<p> <br> +From <b>SiSU</b> 2.7.7 on you can number codeblocks by placing a hash after the +opening code tag code{# as demonstrated here: +<p> <br> +<pre>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."’ +</pre> +<p> +<h2><a name='sect40' href='#toc40'>Additional Breaks - Linebreaks Within Objects, Column and Page-breaks</a></h2> + +<p> +<h2><a name='sect41' href='#toc41'>Line-breaks</a></h2> + +<p> +<br> +To break a line within a "paragraph object", two backslashes \\ with a space +before and a space or newline after them may be used. +<p> <br> +<pre>To break a line within a "paragraph object", +two backslashes \\ with a space before +and a space or newline after them \\ +may be used. +</pre> +<p> <br> +The html break br enclosed in angle brackets (though undocumented) is available +in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being, +but is depreciated). +<p> +<h2><a name='sect42' href='#toc42'>Page Breaks</a></h2> + +<p> <br> +Page breaks are only relevant and honored in some output formats. A page +break or a new page may be inserted manually using the following markup +on a line on its own: +<p> <br> +page new =\= or breaks the page, starts a new page. +<p> <br> +page break -\- or breaks a column, starts a new column, if using columns, +else breaks the page, starts a new page. +<p> <br> +<pre>-\\- +or +<:pb> +</pre> +<p> <br> + +<p>or +<p> <br> +<pre>=\\= +or +<:pn> +</pre> +<p> +<h2><a name='sect43' href='#toc43'>Book Index</a></h2> + +<p> <br> +To make an index append to paragraph the book index term relates to it, +using an equal sign and curly braces. +<p> <br> +Currently two levels are provided, a main term and if needed a sub-term. +Sub-terms are separated from the main term by a colon. +<p> <br> +<pre> Paragraph containing main term and sub-term. + ={Main term:sub-term} +</pre> +<p> <br> +The index syntax starts on a new line, but there should not be an empty +line between paragraph and index markup. +<p> <br> +The structure of the resulting index would be: +<p> <br> +<pre> Main term, 1 + sub-term, 1 +</pre> +<p> <br> +Several terms may relate to a paragraph, they are separated by a semicolon. +If the term refers to more than one paragraph, indicate the number of paragraphs. + +<p> <br> +<pre> Paragraph containing main term, second term and sub-term. + ={first term; second term: sub-term} +</pre> +<p> <br> +The structure of the resulting index would be: +<p> <br> +<pre> First term, 1, + Second term, 1, + sub-term, 1 +</pre> +<p> <br> +If multiple sub-terms appear under one paragraph, they are separated under +the main term heading from each other by a pipe symbol. +<p> <br> +<pre> Paragraph containing main term, second term and sub-term. + ={Main term:sub-term+1|second sub-term} + A paragraph that continues discussion of the first sub-term +</pre> +<p> <br> +The plus one in the example provided indicates the first sub-term spans +one additional paragraph. The logical structure of the resulting index would +be: +<p> <br> +<pre> Main term, 1, + sub-term, 1-3, + second sub-term, 1, +</pre> +<p> +<h2><a name='sect44' href='#toc44'>Composite Documents Markup</a></h2> +<br> + +<p> <br> +It is possible to build a document by creating a master document that requires +other documents. The documents required may be complete documents that could +be generated independently, or they could be markup snippets, prepared +so as to be easily available to be placed within another text. If the calling +document is a master document (built from other documents), it should be +named with the suffix <b>.ssm</b> Within this document you would provide information +on the other documents that should be included within the text. These may +be other documents that would be processed in a regular way, or markup +bits prepared only for inclusion within a master document <b>.sst</b> regular markup +file, or <b>.ssi</b> (insert/information) A secondary file of the composite document + +<p>is built prior to processing with the same prefix and the suffix <b>._sst</b> +<p> +<br> + +<p>basic markup for importing a document into a master document +<p> <br> +<pre><< filename1.sst +<< filename2.ssi +</pre> +<p> <br> +The form described above should be relied on. Within the <i>Vim</i> editor it results +in the text thus linked becoming hyperlinked to the document it is calling +in which is convenient for editing. +<p> +<h2><a name='sect45' href='#toc45'>Sisu Filetypes</a></h2> +<br> + +<p> <br> +<b>SiSU</b> has <i>plaintext</i> and binary filetypes, and can process either type of +document. +<p> +<h2><a name='sect46' href='#toc46'>.sst .ssm .ssi Marked Up Plain Text</a></h2> + +<p> +<dl> + +<dt><b>SiSU¤b〕 documents are prepared +as plain-text (utf-8) files with</b> </dt> +<dd><b>SiSU</b> markup. They may make reference to and +contain images (for example), which are stored in the directory beneath +them _sisu/image. 〔b¤SiSU <i>plaintext</i> markup files are of three types that +may be distinguished by the file extension used: regular text .sst; master +documents, composite documents that incorporate other text, which can be +any regular text or text insert; and inserts the contents of which are +like regular text except these are marked .ssi and are not processed.<br> + +<p> <br> +<b>SiSU</b> processing can be done directly against a sisu documents; which may +be located locally or on a remote server for which a url is provided. +<p> <br> +<b>SiSU</b> source markup can be shared with the command: +<p> <br> + sisu -s [filename]<br> + +<p> </dd> +</dl> + +<h2><a name='sect47' href='#toc47'>Sisu Text - Regular Files (.sst)</a></h2> + +<p> <br> +The most common form of document in <b>SiSU,</b> see the section on <b>SiSU</b> markup. + +<p> +<h2><a name='sect48' href='#toc48'>Sisu Master Files (.ssm)</a></h2> + +<p> <br> +Composite documents which incorporate other <b>SiSU</b> documents which may be +either regular <b>SiSU</b> text .sst which may be generated independently, or inserts +prepared solely for the purpose of being incorporated into one or more +master documents. +<p> <br> +The mechanism by which master files incorporate other documents is described +as one of the headings under under <b>SiSU</b> markup in the <b>SiSU</b> manual. +<p> <br> +Note: Master documents may be prepared in a similar way to regular documents, +and processing will occur normally if a .sst file is renamed .ssm without +requiring any other documents; the .ssm marker flags that the document may +contain other documents. +<p> <br> +Note: a secondary file of the composite document is built prior to processing +with the same prefix and the suffix ._sst [^19] +<p> +<h2><a name='sect49' href='#toc49'>Sisu Insert Files (.ssi)</a></h2> + +<p> +<br> +Inserts are documents prepared solely for the purpose of being incorporated +into one or more master documents. They resemble regular <b>SiSU</b> text files +except they are ignored by the <b>SiSU</b> processor. Making a file a .ssi file +is a quick and convenient way of flagging that it is not intended that +the file should be processed on its own. +<p> +<h2><a name='sect50' href='#toc50'>Sisupod, Zipped Binary Container +(sisupod.zip, .ssp)</a></h2> + +<p> <br> +A sisupod is a zipped <b>SiSU</b> text file or set of <b>SiSU</b> text files and any +associated images that they contain (this will be extended to include sound +and multimedia-files) +<p> +<dl> + +<dt><b>SiSU</b> </dt> +<dd><i>plaintext</i> files rely on a recognised directory +structure to find contents such as images associated with documents, but +all images for example for all documents contained in a directory are located +in the sub-directory _sisu/image. Without the ability to create a sisupod +it can be inconvenient to manually identify all other files associated +with a document. A sisupod automatically bundles all associated files with +the document that is turned into a pod. +<p> <br> +The structure of the sisupod is such that it may for example contain a +single document and its associated images; a master document and its associated +documents and anything else; or the zipped contents of a whole directory +of prepared <b>SiSU</b> documents. +<p> <br> +The command to create a sisupod is: +<p> <br> + sisu -S [filename]<br> + +<p> <br> +Alternatively, make a pod of the contents of a whole directory: +<p> <br> + sisu -S<br> + +<p> <br> +<b>SiSU</b> processing can be done directly against a sisupod; which may be located +locally or on a remote server for which a url is provided. +<p> <br> +<<a href='http://www.sisudoc.org/sisu/sisu_commands'>http://www.sisudoc.org/sisu/sisu_commands</a> +> +<p> <br> +<<a href='http://www.sisudoc.org/sisu/sisu_manual'>http://www.sisudoc.org/sisu/sisu_manual</a> +> +<p> </dd> +</dl> + +<h2><a name='sect51' href='#toc51'>Configuration</a></h2> +<br> + +<p> +<h2><a name='sect52' href='#toc52'>Configuration Files</a></h2> + +<p> +<h2><a name='sect53' href='#toc53'>Config.yml</a></h2> + +<p> <br> +<b>SiSU</b> configration parameters are adjusted in the configuration file, which +can be used to override the defaults set. This includes such things as which +directory interim processing should be done in and where the generated +output should be placed. +<p> <br> +The <b>SiSU</b> configuration file is a yaml file, which means indentation is +significant. +<p> <br> +<b>SiSU</b> resource configuration is determined by looking at the following files +if they exist: +<p> <br> + ./_sisu/v4/sisurc.yml<br> + +<p> <br> + ./_sisu/sisurc.yml<br> + +<p> <br> + ~/.sisu/v4/sisurc.yml<br> + +<p> <br> + ~/.sisu/sisurc.yml<br> + +<p> <br> + /etc/sisu/v4/sisurc.yml<br> + +<p> <br> + /etc/sisu/sisurc.yml<br> + +<p> <br> +The search is in the order listed, and the first one found is used. +<p> <br> +In the absence of instructions in any of these it falls back to the internal +program defaults. +<p> <br> +Configuration determines the output and processing directories and the +database access details. +<p> <br> + +<p>If <b>SiSU</b> is installed a sample sisurc.yml may be found in /etc/sisu/sisurc.yml + +<p> +<h2><a name='sect54' href='#toc54'>Sisu_document_make</a></h2> + +<p> <br> +Most sisu document headers relate to metadata, the exception is the @make: +header which provides processing related information. The default contents +of the @make header may be set by placing them in a file sisu_document_make. + +<p> <br> +The search order is as for resource configuration: +<p> <br> + ./_sisu/v4/sisu_document_make<br> + +<p> <br> + ./_sisu/sisu_document_make<br> + +<p> <br> + ~/.sisu/v4/sisu_document_make<br> + +<p> <br> + ~/.sisu/sisu_document_make<br> + +<p> <br> + /etc/sisu/v4/sisu_document_make<br> + +<p> <br> + /etc/sisu/sisu_document_make<br> + +<p> <br> +A sample sisu_document_make can be found in the _sisu/ directory under +along with the provided sisu markup samples. +<p> +<h2><a name='sect55' href='#toc55'>Css - Cascading Style Sheets +(for Html, Xhtml and Xml)</a></h2> +<br> + +<p> <br> +CSS files to modify the appearance of <b>SiSU</b> html, <i>XHTML</i> or <i>XML</i> may be placed +in the configuration directory: ./_sisu/css ; ~/.sisu/css or; /etc/sisu/css +and these will be copied to the output directories with the command sisu +-CC. +<p> <br> +The basic CSS file for html output is html. css, placing a file of that +name in directory _sisu/css or equivalent will result in the default file +of that name being overwritten. +<p> <br> +<i>HTML:</i> html. css +<p> <br> +<i>XML</i> DOM: dom.css +<p> <br> +<i>XML</i> SAX: sax.css +<p> <br> +<i>XHTML:</i> xhtml. css +<p> <br> +The default homepage may use homepage.css or html. css +<p> <br> +Under consideration is to permit the placement of a CSS file with a different +name in directory _sisu/css directory or equivalent.[^20] +<p> +<h2><a name='sect56' href='#toc56'>Organising Content +- Directory Structure and Mapping</a></h2> +<br> + +<p> <br> +<b>SiSU</b> v3 has new options for the source directory tree, and output directory +structures of which there are 3 alternatives. +<p> +<h2><a name='sect57' href='#toc57'>Document Source Directory</a></h2> + +<p> +<br> +The document source directory is the directory in which sisu processing +commands are given. It contains the sisu source files (.sst .ssm .ssi), or +(for sisu v3 may contain) subdirectories with language codes which contain +the sisu source files, so all English files would go in subdirectory en/, +French in fr/, Spanish in es/ and so on. ISO 639-1 codes are used (as varied +by po4a). A list of available languages (and possible sub-directory names) +can be obtained with the command "sisu --help lang" The list of languages +is limited to langagues supported by XeTeX polyglosia. +<p> +<h2><a name='sect58' href='#toc58'>General Directories</a></h2> + +<p> +<br> +<pre>% files stored at this level e.g. sisu_manual.sst or +% for sisu v3 may be under language sub-directories +% e.g. + ./subject_name/en + ./subject_name/fr + ./subject_name/es + ./subject_name/_sisu + ./subject_name/_sisu/css + ./subject_name/_sisu/image +</pre> +<p> +<h2><a name='sect59' href='#toc59'>Document Output Directory Structures</a></h2> + +<p> +<h2><a name='sect60' href='#toc60'>Output Directory Root</a></h2> + +<p> <br> +The output directory root can be set in the sisurc.yml file. Under the root, +subdirectories are made for each directory in which a document set resides. +If you have a directory named poems or conventions, that directory will +be created under the output directory root and the output for all documents +contained in the directory of a particular name will be generated to subdirectories +beneath that directory (poem or conventions). A document will be placed +in a subdirectory of the same name as the document with the filetype identifier +stripped (.sst .ssm) +<p> <br> +The last part of a directory path, representing the sub-directory in which +a document set resides, is the directory name that will be used for the +output directory. This has implications for the organisation of document +collections as it could make sense to place documents of a particular subject, +or type within a directory identifying them. This grouping as suggested +could be by subject (sales_law, english_literature); or just as conveniently +by some other classification (X University). The mapping means it is also +possible to place in the same output directory documents that are for organisational +purposes kept separately, for example documents on a given subject of two +different institutions may be kept in two different directories of the +same name, under a directory named after each institution, and these would +be output to the same output directory. Skins could be associated with each +institution on a directory basis and resulting documents will take on the +appropriate different appearance. +<p> +<h2><a name='sect61' href='#toc61'>Alternative Output Structures</a></h2> + +<p> <br> +There are 3 possibile output structures described as being, by language, +by filetype or by filename, the selection is made in sisurc.yml +<p> <br> +<pre>#% output_dir_structure_by: language; filetype; or filename +output_dir_structure_by: language #(language & filetype, preferred?) +#output_dir_structure_by: filetype +#output_dir_structure_by: filename #(default, closest to original v1 & +v2) +</pre> +<p> +<h2><a name='sect62' href='#toc62'>by Language</a></h2> + +<p> <br> + +<p>The by language directory structure places output files +<p> <br> +The by language directory structure separates output files by language +code (all files of a given language), and within the language directory +by filetype. +<p> <br> + +<p>Its selection is configured in sisurc.yml +<p> <br> +output_dir_structure_by: language +<p> <br> +<pre> |-- en + |-- epub + |-- hashes + |-- html + | |-- viral_spiral.david_bollier + | |-- manifest + | |-- qrcode + | |-- odt + | |-- pdf + | |-- sitemaps + | |-- txt + | |-- xhtml + | ‘-- xml + |-- po4a + | ‘-- live-manual + | |-- po + | |-- fr + | ‘-- pot + ‘-- _sisu + |-- css + |-- image + |-- image_sys -> ../../_sisu/image_sys + ‘-- xml + |-- rnc + |-- rng + ‘-- xsd +</pre> +<p> <br> +#by: language subject_dir/en/manifest/filename.html +<p> +<h2><a name='sect63' href='#toc63'>by Filetype</a></h2> + +<p> <br> +The by filetype directory structure separates output files by filetype, +all html files in one directory pdfs in another and so on. Filenames are +given a language extension. +<p> <br> + +<p>Its selection is configured in sisurc.yml +<p> <br> +output_dir_structure_by: filetype +<p> <br> +<pre> |-- epub + |-- hashes + |-- html + |-- viral_spiral.david_bollier + |-- manifest + |-- qrcode + |-- odt + |-- pdf + |-- po4a + |-- live-manual + | |-- po + | |-- fr + | ‘-- pot + |-- _sisu + | |-- css + | |-- image + | |-- image_sys -> ../../_sisu/image_sys + | ‘-- xml + | |-- rnc + | |-- rng + | ‘-- xsd + |-- sitemaps + |-- txt + |-- xhtml + ‘-- xml +</pre> +<p> <br> +#by: filetype subject_dir/html/filename/manifest.en.html +<p> +<h2><a name='sect64' href='#toc64'>by Filename</a></h2> + +<p> <br> +The by filename directory structure places most output of a particular +file (the different filetypes) in a common directory. +<p> <br> + +<p>Its selection is configured in sisurc.yml +<p> <br> +output_dir_structure_by: filename +<p> <br> +<pre> |-- epub + |-- po4a + |-- live-manual + | |-- po + | |-- fr + | ‘-- pot + |-- _sisu + | |-- css + | |-- image + | |-- image_sys -> ../../_sisu/image_sys + | ‘-- xml + | |-- rnc + | |-- rng + | ‘-- xsd + |-- sitemaps + |-- src + |-- pod + ‘-- viral_spiral.david_bollier +</pre> +<p> <br> +#by: filename subject_dir/filename/manifest.en.html +<p> +<h2><a name='sect65' href='#toc65'>Remote Directories</a></h2> + +<p> <br> +<pre>% containing sub_directories named after the generated files from which +they are made + ./subject_name/src +% contains shared source files text and binary e.g. sisu_manual.sst and sisu_manual.sst.zip + ./subject_name/_sisu +% configuration file e.g. sisurc.yml + ./subject_name/_sisu/skin +% skins in various skin directories doc, dir, site, yml + ./subject_name/_sisu/css + ./subject_name/_sisu/image +% images for documents contained in this directory + ./subject_name/_sisu/mm +</pre> +<p> +<h2><a name='sect66' href='#toc66'>Sisupod</a></h2> + +<p> <br> +<pre>% files stored at this level e.g. sisu_manual.sst + ./sisupod/_sisu +% configuration file e.g. sisurc.yml + ./sisupod/_sisu/skin +% skins in various skin directories doc, dir, site, yml + ./sisupod/_sisu/css + ./sisupod/_sisu/image +% images for documents contained in this directory + ./sisupod/_sisu/mm +</pre> +<p> +<h2><a name='sect67' href='#toc67'>Organising Content</a></h2> + +<p> +<h2><a name='sect68' href='#toc68'>Homepages</a></h2> +<br> + +<p> <br> +<b>SiSU</b> is about the ability to auto-generate documents. Home pages are regarded +as custom built items, and are not created by <b>SiSU.</b> More accurately, <b>SiSU</b> +has a default home page, which will not be appropriate for use with other +sites, and the means to provide your own home page instead in one of two +ways as part of a site’s configuration, these being: +<p> <br> +1. through placing your home page and other custom built documents in the +subdirectory _sisu/home/ (this probably being the easier and more convenient +option) +<p> <br> +2. through providing what you want as the home page in a skin, +<p> <br> +Document sets are contained in directories, usually organised by site or +subject. Each directory can/should have its own homepage. See the section +on directory structure and organisation of content. +<p> +<h2><a name='sect69' href='#toc69'>Home Page and Other +Custom Built Pages in a Sub-directory</a></h2> + +<p> <br> +Custom built pages, including the home page index.html may be placed within +the configuration directory _sisu/home/ in any of the locations that is +searched for the configuration directory, namely ./_sisu ; ~/_sisu ; /etc/sisu +From there they are copied to the root of the output directory with the +command: +<p> <br> + sisu -CC<br> + +<p> +<h2><a name='sect70' href='#toc70'>Markup and Output Examples</a></h2> +<br> + +<p> +<h2><a name='sect71' href='#toc71'>Markup Examples</a></h2> + +<p> <br> +Current markup examples and document output samples are provided off <<a href='http://sisudoc.org'>http://sisudoc.org</a> +> +or <<a href='http://www.jus.uio.no/sisu'>http://www.jus.uio.no/sisu</a> +> and in the sisu -markup-sample package available +off <<a href='http://sources.sisudoc.org'>http://sources.sisudoc.org</a> +> +<p> <br> +For some documents hardly any markup at all is required at all, other than +a header, and an indication that the levels to be taken into account by +the program in generating its output are. +<p> +<h2><a name='sect72' href='#toc72'>Sisu Markup Samples</a></h2> + +<p> <br> +A few additional sample books prepared as sisu markup samples, output formats +to be generated using <b>SiSU</b> are contained in a separate package sisu -markup-samples. +sisu -markup-samples contains books (prepared using sisu markup), that were +released by their authors various licenses mostly different Creative Commons +licences that do not permit inclusion in the <b>Debian</b> Project as they have +requirements that do not meet the <b>Debian</b> Free Software Guidelines for various +reasons, most commonly that they require that the original substantive +text remain unchanged, and sometimes that the works be used only non-commercially. + +<p> <br> +<i>Accelerando,</i> Charles Stross (2005) accelerando.charles_stross.sst +<p> <br> +<i>Alice’s</i> Adventures in Wonderland, Lewis Carroll (1865) alices_adventures_in_wonderland.lewis_carroll.sst + +<p> <br> +<i>CONTENT,</i> Cory Doctorow (2008) content.cory_doctorow.sst +<p> <br> +<i>Democratizing</i> Innovation, Eric von Hippel (2005) democratizing_innovation.eric_von_hippel.sst + +<p> <br> +<i>Down</i> and Out in the Magic Kingdom, Cory Doctorow (2003) down_and_out_in_the_magic_kingdom.cory_doctorow.sst + +<p> <br> +<i>For</i> the Win, Cory Doctorow (2010) for_the_win.cory_doctorow.sst +<p> <br> +<i>Free</i> as in Freedom - Richard Stallman’s Crusade for Free Software, Sam Williams +(2002) free_as_in_freedom.richard_stallman_crusade_for_free_software.sam_williams.sst + +<p> <br> +<i>Free</i> as in Freedom 2.0 - Richard Stallman and the Free Software Revolution, +Sam Williams (2002), Richard M. Stallman (2010) free_as_in_freedom_2.richard_stallman_and_the_free_software_revolution.sam_williams.richard_stallman.sst + +<p> <br> +<i>Free</i> Culture - How Big Media Uses Technology and the Law to Lock Down Culture +and Control Creativity, Lawrence Lessig (2004) free_culture.lawrence_lessig.sst + +<p> <br> +<i>Free</i> For All - How Linux and the Free Software Movement Undercut the High +Tech Titans, Peter Wayner (2002) free_for_all.peter_wayner.sst +<p> <br> +<i>GNU</i> GENERAL PUBLIC LICENSE v2, Free Software Foundation (1991) gpl2.fsf.sst + +<p> <br> +<i>GNU</i> GENERAL PUBLIC LICENSE v3, Free Software Foundation (2007) gpl3.fsf.sst + +<p> <br> +<i>Gulliver’s</i> Travels, Jonathan Swift (1726 / 1735) gullivers_travels.jonathan_swift.sst + +<p> <br> +<i>Little</i> Brother, Cory Doctorow (2008) little_brother.cory_doctorow.sst +<p> <br> +<i>The</i> Cathederal and the Bazaar, Eric Raymond (2000) the_cathedral_and_the_bazaar.eric_s_raymond.sst + +<p> <br> +<i>The</i> Public Domain - Enclosing the Commons of the Mind, James Boyle (2008) + +<p>the_public_domain.james_boyle.sst +<p> <br> +<i>The</i> Wealth of Networks - How Social Production Transforms Markets and Freedom, +Yochai Benkler (2006) the_wealth_of_networks.yochai_benkler.sst +<p> <br> +<i>Through</i> the Looking Glass, Lewis Carroll (1871) through_the_looking_glass.lewis_carroll.sst + +<p> <br> +<i>Two</i> Bits - The Cultural Significance of Free Software, Christopher Kelty +(2008) two_bits.christopher_kelty.sst +<p> <br> +<i>UN</i> Contracts for International Sale of Goods, UN (1980) un_contracts_international_sale_of_goods_convention_1980.sst + +<p> <br> +<i>Viral</i> Spiral, David Bollier (2008) viral_spiral.david_bollier.sst +<p> +<h2><a name='sect73' href='#toc73'>Sisu Search +- Introduction</a></h2> +<br> + +<p> <br> +<b>SiSU</b> output can easily and conveniently be indexed by a number of standalone +indexing tools, such as Lucene, Hyperestraier. +<p> <br> +Because the document structure of sites created is clearly defined, and +the text <i>object</i> citation system is available hypothetically at least, for +all forms of output, it is possible to search the sql database, and either +read results from that database, or just as simply map the results to the +html output, which has richer text markup. +<p> <br> +In addition to this <b>SiSU</b> has the ability to populate a relational sql type +database with documents at an object level, with objects numbers that are +shared across different output types, which make them searchable with that +degree of granularity. Basically, your match criteria is met by these documents +and at these locations within each document, which can be viewed within +the database directly or in various output formats. +<p> +<h2><a name='sect74' href='#toc74'>Sql</a></h2> +<br> + +<p> +<h2><a name='sect75' href='#toc75'>Populating Sql Type Databases</a></h2> + +<p> <br> +<b>SiSU</b> feeds sisu markupd documents into sql type databases <i>PostgreSQL</i> [^21] +and/or <i>SQLite</i> [^22] database together with information related to document +structure. +<p> <br> +This is one of the more interesting output forms, as all the structural +data of the documents are retained (though can be ignored by the user of +the database should they so choose). All site texts/documents are (currently) +streamed to four tables: +<p> <br> + * one containing semantic (and other) headers, including, title, author,<br> + subject, (the<br> + .I Dublin Core.<br> + ..);<br> + +<p> <br> + * another the substantive texts by individual "paragraph" (or object) +-<br> + along with structural information, each paragraph being identifiable +by its<br> + paragraph number (if it has one which almost all of them do), and the<br> + substantive text of each paragraph quite naturally being searchable +(both in<br> + formatted and clean text versions for searching); and<br> + +<p> <br> + * a third containing endnotes cross-referenced back to the paragraph from<br> + which they are referenced (both in formatted and clean text versions +for<br> + searching).<br> + +<p> <br> + * a fourth table with a one to one relation with the headers table contains<br> + full text versions of output, eg. pdf, html, xml, and<br> + .I ascii.<br> + +<p> <br> +There is of course the possibility to add further structures. +<p> <br> +At this level <b>SiSU</b> loads a relational database with documents chunked into +objects, their smallest logical structurally constituent parts, as text +objects, with their object citation number and all other structural information +needed to construct the document. Text is stored (at this text object level) +with and without elementary markup tagging, the stripped version being +so as to facilitate ease of searching. +<p> <br> +Being able to search a relational database at an object level with the +<b>SiSU</b> citation system is an effective way of locating content generated +by <b>SiSU.</b> As individual text objects of a document stored (and indexed) together +with object numbers, and all versions of the document have the same numbering, +complex searches can be tailored to return just the locations of the search +results relevant for all available output formats, with live links to the +precise locations in the database or in html/xml documents; or, the structural +information provided makes it possible to search the full contents of the +database and have headings in which search content appears, or to search +only headings etc. (as the <i>Dublin</i> Core is incorporated it is easy to make +use of that as well). +<p> +<h2><a name='sect76' href='#toc76'>Postgresql</a></h2> +<br> + +<p> +<h2><a name='sect77' href='#toc77'>Name</a></h2> + +<p> <br> +<b>SiSU</b> - Structured information, Serialized Units - a document publishing system, + +<p>postgresql dependency package +<p> +<h2><a name='sect78' href='#toc78'>Description</a></h2> + +<p> <br> +Information related to using postgresql with sisu (and related to the sisu_postgresql +dependency package, which is a dummy package to install dependencies needed +for <b>SiSU</b> to populate a postgresql database, this being part of <b>SiSU</b> - man +sisu) . +<p> +<h2><a name='sect79' href='#toc79'>Synopsis</a></h2> + +<p> <br> + sisu -D [instruction] [filename/wildcard if required]<br> + +<p> <br> + sisu -D --pg --[instruction] [filename/wildcard if required]<br> + +<p> +<h2><a name='sect80' href='#toc80'>Commands</a></h2> + +<p> <br> +Mappings to two databases are provided by default, postgresql and sqlite, +the same commands are used within sisu to construct and populate databases +however -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql, + +<p>alternatively --sqlite or --pgsql may be used +<p> <br> +<b>-D or --pgsql</b> may be used interchangeably. +<p> +<h2><a name='sect81' href='#toc81'>Create and Destroy Database</a></h2> + +<p> +<dl> + +<dt><b>--pgsql +--createall</b> </dt> +<dd>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) +<p> </dd> + +<dt><b>sisu -D +--createdb</b> </dt> +<dd>creates database where no database existed before +<p> </dd> + +<dt><b>sisu -D --create</b> +</dt> +<dd> +<p>creates database tables where no database tables existed before +<p> </dd> + +<dt><b>sisu -D +--Dropall</b> </dt> +<dd>destroys database (including all its content)! kills data and drops +tables, indexes and database associated with a given directory (and directories +of the same name). +<p> </dd> + +<dt><b>sisu -D --recreate</b> </dt> +<dd>destroys existing database and builds + +<p>a new empty database structure +<p> </dd> +</dl> + +<h2><a name='sect82' href='#toc82'>Import and Remove Documents</a></h2> + +<p> +<dl> + +<dt><b>sisu -D --import +-v [filename/wildcard]</b> </dt> +<dd>populates database with the contents of the file. +Imports documents(s) specified to a postgresql database (at an object level). + +<p> </dd> + +<dt><b>sisu -D --update -v [filename/wildcard]</b> </dt> +<dd>updates file contents in database + +<p> </dd> + +<dt><b>sisu -D --remove -v [filename/wildcard]</b> </dt> +<dd>removes specified document from postgresql +database. +<p> </dd> +</dl> + +<h2><a name='sect83' href='#toc83'>Sqlite</a></h2> +<br> + +<p> +<h2><a name='sect84' href='#toc84'>Name</a></h2> + +<p> <br> +<b>SiSU</b> - Structured information, Serialized Units - a document publishing system. + +<p> +<h2><a name='sect85' href='#toc85'>Description</a></h2> + +<p> <br> +Information related to using sqlite with sisu (and related to the sisu_sqlite +dependency package, which is a dummy package to install dependencies needed +for <b>SiSU</b> to populate an sqlite database, this being part of <b>SiSU</b> - man sisu) +. +<p> +<h2><a name='sect86' href='#toc86'>Synopsis</a></h2> + +<p> <br> + sisu -d [instruction] [filename/wildcard if required]<br> + +<p> <br> + sisu -d --(sqlite|pg) --[instruction] [filename/wildcard if <br> + required]<br> + +<p> +<h2><a name='sect87' href='#toc87'>Commands</a></h2> + +<p> <br> +Mappings to two databases are provided by default, postgresql and sqlite, +the same commands are used within sisu to construct and populate databases +however -d (lowercase) denotes sqlite and -D (uppercase) denotes postgresql, + +<p>alternatively --sqlite or --pgsql may be used +<p> <br> +<b>-d or --sqlite</b> may be used interchangeably. +<p> +<h2><a name='sect88' href='#toc88'>Create and Destroy Database</a></h2> + +<p> +<dl> + +<dt><b>--sqlite +--createall</b> </dt> +<dd>initial step, creates required relations (tables, indexes) in +existing (sqlite) database (a database should be created manually and given +the same name as working directory, as requested) (rb.dbi) +<p> </dd> + +<dt><b>sisu -d --createdb</b> +</dt> +<dd> +<p>creates database where no database existed before +<p> </dd> + +<dt><b>sisu -d --create</b> </dt> +<dd>creates + +<p>database tables where no database tables existed before +<p> </dd> + +<dt><b>sisu -d --dropall</b> +</dt> +<dd>destroys database (including all its content)! kills data and drops tables, +indexes and database associated with a given directory (and directories +of the same name). +<p> </dd> + +<dt><b>sisu -d --recreate</b> </dt> +<dd>destroys existing database and builds + +<p>a new empty database structure +<p> </dd> +</dl> + +<h2><a name='sect89' href='#toc89'>Import and Remove Documents</a></h2> + +<p> +<dl> + +<dt><b>sisu -d --import +-v [filename/wildcard]</b> </dt> +<dd>populates database with the contents of the file. +Imports documents(s) specified to an sqlite database (at an object level). + +<p> </dd> + +<dt><b>sisu -d --update -v [filename/wildcard]</b> </dt> +<dd>updates file contents in database + +<p> </dd> + +<dt><b>sisu -d --remove -v [filename/wildcard]</b> </dt> +<dd>removes specified document from sqlite +database. +<p> </dd> +</dl> + +<h2><a name='sect90' href='#toc90'>Introduction</a></h2> +<br> + +<p> +<h2><a name='sect91' href='#toc91'>Search - Database Frontend Sample, Utilising Database and Sisu Features,</a></h2> +INCLUDING +OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL) +<p> <br> +Sample search frontend <<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> +> [^23] A small database and +sample query front-end (search from) that makes use of the citation system, +<i>object</i> citation numbering to demonstrates functionality.[^24] +<p> <br> +<b>SiSU</b> can provide information on which documents are matched and at what +locations within each document the matches are found. These results are +relevant across all outputs using <i>object</i> citation numbering, which includes +html, <i>XML,</i> <i>EPUB,</i> <i>LaTeX,</i> <i>PDF</i> and indeed the <i>SQL</i> database. You can then refer +to one of the other outputs or in the <i>SQL</i> database expand the text within +the matched objects (paragraphs) in the documents matched. +<p> <br> +Note you may set results either for documents matched and object number +locations within each matched document meeting the search criteria; or +display the names of the documents matched along with the objects (paragraphs) +that meet the search criteria.[^25] +<p> +<dl> + +<dt><b>sisu -F --webserv-webrick</b> </dt> +<dd>builds a cgi web + +<p>search frontend for the database created +<p> <br> +The following is feedback on the setup on a machine provided by the help +command: +<p> <br> + sisu --help sql<br> + +<p> <br> +<pre>Postgresql + user: ralph + current db set: SiSU_sisu + port: 5432 + dbi connect: DBI:Pg:database=SiSU_sisu;port=5432 +sqlite + current db set: /home/ralph/sisu_www/sisu/sisu_sqlite.db + dbi connect DBI:SQLite:/home/ralph/sisu_www/sisu/sisu_sqlite.db +</pre> +<p> <br> + +<p>Note on databases built +<p> <br> +By default, [unless otherwise specified] databases are built on a directory +basis, from collections of documents within that directory. The name of +the directory you choose to work from is used as the database name, i.e. +if you are working in a directory called /home/ralph/ebook the database +SiSU_ebook is used. [otherwise a manual mapping for the collection is +<p> </dd> +</dl> + +<h2><a name='sect92' href='#toc92'>Search +Form</a></h2> + +<p> +<dl> + +<dt><b>sisu -F</b> </dt> +<dd>generates a sample search form, which must be copied to the + +<p>web-server cgi directory +<p> </dd> + +<dt><b>sisu -F --webserv-webrick</b> </dt> +<dd>generates a sample search +form for use with the webrick server, which must be copied to the web-server + +<p>cgi directory +<p> </dd> + +<dt><b>sisu -W</b> </dt> +<dd>starts the webrick server which should be available + +<p>wherever sisu is properly installed +<p> <br> + +<p>The generated search form must be copied manually to the webserver directory + +<p>as instructed +<p> </dd> +</dl> + +<h2><a name='sect93' href='#toc93'>Sisu_webrick</a></h2> +<br> + +<p> +<h2><a name='sect94' href='#toc94'>Name</a></h2> + +<p> <br> +<b>SiSU</b> - Structured information, Serialized Units - a document publishing system + +<p> +<h2><a name='sect95' href='#toc95'>Synopsis</a></h2> + +<p> <br> +sisu_webrick [port] +<p> <br> + +<p>or +<p> <br> +sisu -W [port] +<p> +<h2><a name='sect96' href='#toc96'>Description</a></h2> + +<p> <br> +sisu_webrick is part of <b>SiSU</b> (man sisu) sisu_webrick starts <b>Ruby</b> <b>SiSU</b> +output is written, providing a list of these directories (assuming <b>SiSU</b> +is in use and they exist). +<p> <br> +The default port for sisu_webrick is set to 8081, this may be modified +in the yaml file: ~/.sisu/sisurc.yml a sample of which is provided as /etc/sisu/sisurc.yml +(or in the equivalent directory on your system). +<p> +<h2><a name='sect97' href='#toc97'>Summary of Man Page</a></h2> + +<p> <br> +sisu_webrick, may be started on it’s own with the command: sisu_webrick +[port] or using the sisu command with the -W flag: sisu -W [port] +<p> <br> + +<p>where no port is given and settings are unchanged the default port is 8081 + +<p> +<h2><a name='sect98' href='#toc98'>Document Processing Command Flags</a></h2> + +<p> <br> +sisu -W [port] starts <b>Ruby</b> Webrick web-server, serving <b>SiSU</b> output directories, +on the port provided, or if no port is provided and the defaults have not + +<p>been changed in ~/.sisu/sisurc.yaml then on port 8081 +<p> +<h2><a name='sect99' href='#toc99'>Summary of Features</a></h2> +<br> + +<p> <br> +* sparse/minimal markup (clean utf-8 source texts). Documents are prepared +in a single <i>UTF-8</i> file using a minimalistic mnemonic syntax. Typical literature, +documents like "War and Peace" require almost no markup, and most of the +headers are optional. +<p> <br> +* markup is easily readable/parsable by the human eye, (basic markup is +simpler and more sparse than the most basic <i>HTML</i> ) , [this may also be + converted to .I XML representations of the same input/source document]. +<p> +<br> +* markup defines document structure (this may be done once in a header +pattern-match description, or for heading levels individually); basic text +attributes (bold, italics, underscore, strike-through etc.) as required; +and semantic information related to the document (header information, extended +beyond the Dublin core and easily further extended as required); the headers +may also contain processing instructions. <b>SiSU</b> markup is primarily an abstraction +of document structure and document metadata to permit taking advantage +of the basic strengths of existing alternative practical standard ways +of representing documents [be that browser viewing, paper publication, + sql search etc.] (html, epub, xml, odf, latex, pdf, sql) +<p> <br> +* for output produces reasonably elegant output of established industry +and institutionally accepted open standard formats.[3] takes advantage of +the different strengths of various standard formats for representing documents, +amongst the output formats currently supported are: +<p> <br> +* <i>HTML</i> - both as a single scrollable text and a segmented document +<p> <br> +* <i>XHTML</i> +<p> <br> +* <i>EPUB</i> +<p> <br> +* <i>XML</i> - both in sax and dom style xml structures for further development + +<p>as required +<p> <br> +* <i>ODT</i> - Open Document Format text, the iso standard for document storage + +<p> <br> +* <i>LaTeX</i> - used to generate pdf +<p> <br> +* <i>PDF</i> (via <i>LaTeX</i> ) +<p> <br> +* <i>SQL</i> - population of an sql database ( <i>PostgreSQL</i> or <i>SQLite</i> ) , (at the +same object level that is used to cite text within a document) +<p> <br> +Also produces: concordance files; document content certificates (md5 or +sha256 digests of headings, paragraphs, images etc.) and html manifests +(and sitemaps of content). (b) takes advantage of the strengths implicit +in these very different output types, (e.g. PDFs produced using typesetting +of <i>LaTeX,</i> databases populated with documents at an individual object/paragraph +level, making possible <i>granular</i> search (and related possibilities)) +<p> <br> +* ensuring content can be cited in a meaningful way regardless of selected +output format. Online publishing (and publishing in multiple document formats) +lacks a useful way of citing text internally within documents (important +to academics generally and to lawyers) as page numbers are meaningless +across browsers and formats. sisu seeks to provide a common way of pinpoint +the text within a document, (which can be utilized for citation and by +search engines). The outputs share a common numbering system that is meaningful +(to man and machine) across all digital outputs whether paper, screen, +or database oriented, (pdf, <i>HTML,</i> <i>EPUB,</i> xml, sqlite, postgresql) , this +numbering system can be used to reference content. +<p> <br> +* Granular search within documents. <i>SQL</i> databases are populated at an object +level (roughly headings, paragraphs, verse, tables) and become searchable +with that degree of granularity, the output information provides the object/paragraph +numbers which are relevant across all generated outputs; it is also possible +to look at just the matching paragraphs of the documents in the database; +[output indexing also work +<p> <br> +* long term maintainability of document collections in a world of changing +formats, having a very sparsely marked-up source document base. there is +a considerable degree of future-proofing, output representations are "upgradeable", +and new document formats may be added. e.g. addition of odf (open document +text) module in 2006, epub in 2009 and in future html5 output sometime +in future, without modification of existing prepared texts +<p> <br> +* <i>SQL</i> search aside, documents are generated as required and static once +generated. +<p> <br> +* documents produced are static files, and may be batch processed, this +needs to be done only once but may be repeated for various reasons as desired +(updated content, addition of new output formats, updated technology document +presentations/representations) +<p> <br> +* document source ( <i>plaintext</i> utf-8) if shared on the net may be used as + +<p>input and processed locally to produce the different document outputs +<p> +<br> +* document source may be bundled together (automatically) with associated +documents (multiple language versions or master document with inclusions) +and images and sent as a zip file called a sisupod, if shared on the net + +<p>these too may be processed locally to produce the desired document outputs + +<p> <br> +* generated document outputs may automatically be posted to remote sites. + +<p> <br> +* for basic document generation, the only software dependency is <b>Ruby,</b> +and a few standard Unix tools (this covers <i>plaintext,</i> <i>HTML,</i> <i>EPUB,</i> <i>XML,</i> +<i>ODF,</i> <i>LaTeX</i> ) . To use a database you of course need that, and to convert +the <i>LaTeX</i> generated to pdf, a latex processor like tetex or texlive. +<p> <br> +* as a developers tool it is flexible and extensible +<p> <br> +Syntax highlighting for <b>SiSU</b> markup is available for a number of text editors. + +<p> <br> +<b>SiSU</b> is less about document layout than about finding a way with little +markup to be able to construct an abstract representation of a document +that makes it possible to produce multiple representations of it which +may be rather different from each other and used for different purposes, +whether layout and publishing, or search of content +<p> <br> +i.e. to be able to take advantage from this minimal preparation starting +point of some of the strengths of rather different established ways of +representing documents for different purposes, whether for search (relational +database, or indexed flat files generated for that purpose whether of complete +documents, or say of files made up of objects), online viewing (e.g. html, +xml, pdf) , or paper publication (e.g. pdf) ... +<p> <br> +the solution arrived at is by extracting structural information about the +document (about headings within the document) and by tracking objects (which +are serialized and also given hash values) in the manner described. It makes +possible representations that are quite different from those offered at +present. For example objects could be saved individually and identified +by their hashes, with an index of how the objects relate to each other +to form a document. +<p> +<ol> +<b>.</b><li>objects include: headings, paragraphs, verse, tables, +images, but not footnotes/endnotes which are numbered separately and tied +to the object from which they are referenced. +<p> <br> +</li><b>.</b><li>i.e. the +<p> <br> +<i>HTML,</i> +<p> <br> +<i>PDF,</i> +<p> <br> +<i>EPUB,</i> +<p> <br> + +<p><i>ODT</i> +<p> <br> +outputs are each built individually and optimised for that form of presentation, +rather than for example the html being a saved version of the odf, or the +pdf being a saved version of the html. +<p> <br> +</li><b>.</b><li> +<p>the different heading levels +<p> <br> +</li><b>.</b><li>units of text, primarily paragraphs and headings, also any tables, poems, + +<p>code-blocks +<p> <br> +</li><b>.</b><li> +<p>An open standard format for e-books +<p> <br> +</li><b>.</b><li>Open Document Format ( +<p> <br> + +<p><i>ODF</i> +<p> <br> +) text +<p> <br> +</li><b>.</b><li> +<p>Specification submitted by Adobe to ISO to become a full open ISO specification + +<p> <br> +<<a href='http://www.linux-watch.com/news/NS7542722606.html'>http://www.linux-watch.com/news/NS7542722606.html</a> +> +<p> <br> +</li><b>.</b><li> +<p>ISO standard ISO/IEC 26300:2006 +<p> <br> +</dd> + +<dt><b>*1.</b> </dt> +<dd>square brackets +<p> <br> +</dd> + +<dt><b>*2.</b> </dt> +<dd>square brackets +<p> <br> +</dd> + +<dt><b>+1.</b> </dt> +<dd>square brackets +<p> <br> +</li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/'>http://www.jus.uio.no/sisu/man/</a> +> +<p> <br> +</li><b>.</b><li><<a href='http://www.jus.uio.no/sisu/man/sisu.1.html'>http://www.jus.uio.no/sisu/man/sisu.1.html</a> +> +<p> <br> +</li><b>.</b><li>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. +<p> <br> +</li><b>.</b><li> +<p>files should be prepared using +<p> <br> + +<p><i>UTF-8</i> +<p> <br> + +<p>character encoding +<p> <br> +</li><b>.</b><li> +<p>a footnote or endnote +<p> <br> +</li><b>.</b><li>self contained endnote marker & endnote in one +<p> <br> +</dd> + +<dt><b>*.</b> </dt> +<dd>unnumbered asterisk footnote/endnote, insert multiple asterisks if required + +<p> <br> +</dd> + +<dt><b>**.</b> </dt> +<dd>another unnumbered asterisk footnote/endnote +<p> <br> +</dd> + +<dt><b>*3.</b> </dt> +<dd>editors notes, numbered asterisk footnote/endnote series +<p> <br> +</dd> + +<dt><b>+2.</b> </dt> +<dd>editors notes, numbered asterisk footnote/endnote series +<p> <br> +</li><b>.</b><li><<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +<p> <br> +</li><b>.</b><li><<a href='http://www.ruby-lang.org/en/'>http://www.ruby-lang.org/en/</a> +> +<p> <br> +</li><b>.</b><li> +<p>Table from the Wealth of Networks by Yochai Benkler +<p> <br> +<<a href='http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler'>http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler</a> +> +<p> <br> +</li><b>.</b><li>.ssc (for composite) is under consideration but ._sst makes clear that this +is not a regular file to be worked on, and thus less likely that people +will have "accidents", working on a .ssc file that is overwritten by subsequent +processing. It may be however that when the resulting file is shared .ssc +is an appropriate suffix to use. +<p> <br> +</li><b>.</b><li><<a href='http://www.postgresql.org/'>http://www.postgresql.org/</a> +> +<p> <br> +<<a href='http://advocacy.postgresql.org/'>http://advocacy.postgresql.org/</a> +> +<p> <br> +<<a href='http://en.wikipedia.org/wiki/Postgresql'>http://en.wikipedia.org/wiki/Postgresql</a> +> +<p> <br> +</li><b>.</b><li><<a href='http://www.hwaci.com/sw/sqlite/'>http://www.hwaci.com/sw/sqlite/</a> +> +<p> <br> +<<a href='http://en.wikipedia.org/wiki/Sqlite'>http://en.wikipedia.org/wiki/Sqlite</a> +> +<p> <br> +</li><b>.</b><li><<a href='http://search.sisudoc.org'>http://search.sisudoc.org</a> +> +<p> <br> +</li><b>.</b><li>(which could be extended further with current back-end). As regards scaling +of the database, it is as scalable as the database (here Postgresql) and +hardware allow. +<p> <br> +</li><b>.</b><li>of this feature when demonstrated to an IBM software innovations evaluator +in 2004 he said to paraphrase: this could be of interest to us. We have +large document management systems, you can search hundreds of thousands +of documents and we can tell you which documents meet your search criteria, +but there is no way we can tell you without opening each document where +within each your matches are found. +<p> <br> + +<p> </li> +</ol> + +<h2><a name='sect100' href='#toc100'>See Also</a></h2> + <a href='http:~/bin/man2html?sisu:1'>sisu(1)</a> +,<br> + <a href='http:~/bin/man2html?sisu-epub:1'>sisu-epub(1)</a> +,<br> + <a href='http:~/bin/man2html?sisu-harvest:1'>sisu-harvest(1)</a> +,<br> + <a href='http:~/bin/man2html?sisu-html:1'>sisu-html(1)</a> +,<br> + <a href='http:~/bin/man2html?sisu-odf:1'>sisu-odf(1)</a> +,<br> + <a href='http:~/bin/man2html?sisu-pdf:1'>sisu-pdf(1)</a> +,<br> + <a href='http:~/bin/man2html?sisu-pg:1'>sisu-pg(1)</a> +,<br> + <a href='http:~/bin/man2html?sisu-sqlite:1'>sisu-sqlite(1)</a> +,<br> + <a href='http:~/bin/man2html?sisu-txt:1'>sisu-txt(1)</a> +.<br> + <a href='http:~/bin/man2html?sisu_vim:7'>sisu_vim(7)</a> +<br> + +<h2><a name='sect101' href='#toc101'>Homepage</a></h2> + More information about SiSU can be found at <<a href='http://www.sisudoc.org/'>http://www.sisudoc.org/</a> +> +or <<a href='http://www.jus.uio.no/sisu/'>http://www.jus.uio.no/sisu/</a> +><br> + +<h2><a name='sect102' href='#toc102'>Source</a></h2> + <<a href='http://sources.sisudoc.org/'>http://sources.sisudoc.org/</a> +><br> + +<h2><a name='sect103' href='#toc103'>Author</a></h2> + SiSU is written by Ralph Amissah <ralph@amissah.com><br> + <p> + +<hr><p> +<a name='toc'><b>Table of Contents</b></a><p> +<ul> +<li><a name='toc0' href='#sect0'>Name</a></li> +<li><a name='toc1' href='#sect1'>Synopsis</a></li> +<li><a name='toc2' href='#sect2'>Sisu - Manual,</a></li> +<li><a name='toc3' href='#sect3'>What is Sisu?</a></li> +<li><a name='toc4' href='#sect4'>Introduction - What is Sisu?</a></li> +<li><a name='toc5' href='#sect5'>Commands Summary</a></li> +<li><a name='toc6' href='#sect6'>Description</a></li> +<li><a name='toc7' href='#sect7'>Document Processing Command Flags</a></li> +<li><a name='toc8' href='#sect8'>Command Line Modifiers</a></li> +<li><a name='toc9' href='#sect9'>Database Commands</a></li> +<li><a name='toc10' href='#sect10'>Shortcuts, Shorthand for Multiple Flags</a></li> +<li><a name='toc11' href='#sect11'>Command Line with Flags - Batch Processing</a></li> +<li><a name='toc12' href='#sect12'>Help</a></li> +<li><a name='toc13' href='#sect13'>Sisu Manual</a></li> +<li><a name='toc14' href='#sect14'>Sisu Man Pages</a></li> +<li><a name='toc15' href='#sect15'>Sisu Built-in Interactive Help</a></li> +<li><a name='toc16' href='#sect16'>Introduction to Sisu Markup[^11]</a></li> +<li><a name='toc17' href='#sect17'>Summary</a></li> +<li><a name='toc18' href='#sect18'>Markup Examples</a></li> +<li><a name='toc19' href='#sect19'>Online</a></li> +<li><a name='toc20' href='#sect20'>Installed</a></li> +<li><a name='toc21' href='#sect21'>Markup of Headers</a></li> +<li><a name='toc22' href='#sect22'>Sample Header</a></li> +<li><a name='toc23' href='#sect23'>Available Headers</a></li> +<li><a name='toc24' href='#sect24'>Markup of Substantive Text</a></li> +<li><a name='toc25' href='#sect25'>Heading Levels</a></li> +<li><a name='toc26' href='#sect26'>Font Attributes</a></li> +<li><a name='toc27' href='#sect27'>Indentation and Bullets</a></li> +<li><a name='toc28' href='#sect28'>Hanging Indents</a></li> +<li><a name='toc29' href='#sect29'>Footnotes / Endnotes</a></li> +<li><a name='toc30' href='#sect30'>Links</a></li> +<li><a name='toc31' href='#sect31'>Naked Urls Within Text, Dealing with Urls</a></li> +<li><a name='toc32' href='#sect32'>Linking Text</a></li> +<li><a name='toc33' href='#sect33'>Linking Images</a></li> +<li><a name='toc34' href='#sect34'>Link Shortcut for Multiple Versions of a Sisu Document in the Same Directory</a></li> +<li><a name='toc35' href='#sect35'>Grouped Text</a></li> +<li><a name='toc36' href='#sect36'>Tables</a></li> +<li><a name='toc37' href='#sect37'>Poem</a></li> +<li><a name='toc38' href='#sect38'>Group</a></li> +<li><a name='toc39' href='#sect39'>Code</a></li> +<li><a name='toc40' href='#sect40'>Additional Breaks - Linebreaks Within Objects, Column and Page-breaks</a></li> +<li><a name='toc41' href='#sect41'>Line-breaks</a></li> +<li><a name='toc42' href='#sect42'>Page Breaks</a></li> +<li><a name='toc43' href='#sect43'>Book Index</a></li> +<li><a name='toc44' href='#sect44'>Composite Documents Markup</a></li> +<li><a name='toc45' href='#sect45'>Sisu Filetypes</a></li> +<li><a name='toc46' href='#sect46'>.sst .ssm .ssi Marked Up Plain Text</a></li> +<li><a name='toc47' href='#sect47'>Sisu Text - Regular Files (.sst)</a></li> +<li><a name='toc48' href='#sect48'>Sisu Master Files (.ssm)</a></li> +<li><a name='toc49' href='#sect49'>Sisu Insert Files (.ssi)</a></li> +<li><a name='toc50' href='#sect50'>Sisupod, Zipped Binary Container (sisupod.zip, .ssp)</a></li> +<li><a name='toc51' href='#sect51'>Configuration</a></li> +<li><a name='toc52' href='#sect52'>Configuration Files</a></li> +<li><a name='toc53' href='#sect53'>Config.yml</a></li> +<li><a name='toc54' href='#sect54'>Sisu_document_make</a></li> +<li><a name='toc55' href='#sect55'>Css - Cascading Style Sheets (for Html, Xhtml and Xml)</a></li> +<li><a name='toc56' href='#sect56'>Organising Content - Directory Structure and Mapping</a></li> +<li><a name='toc57' href='#sect57'>Document Source Directory</a></li> +<li><a name='toc58' href='#sect58'>General Directories</a></li> +<li><a name='toc59' href='#sect59'>Document Output Directory Structures</a></li> +<li><a name='toc60' href='#sect60'>Output Directory Root</a></li> +<li><a name='toc61' href='#sect61'>Alternative Output Structures</a></li> +<li><a name='toc62' href='#sect62'>by Language</a></li> +<li><a name='toc63' href='#sect63'>by Filetype</a></li> +<li><a name='toc64' href='#sect64'>by Filename</a></li> +<li><a name='toc65' href='#sect65'>Remote Directories</a></li> +<li><a name='toc66' href='#sect66'>Sisupod</a></li> +<li><a name='toc67' href='#sect67'>Organising Content</a></li> +<li><a name='toc68' href='#sect68'>Homepages</a></li> +<li><a name='toc69' href='#sect69'>Home Page and Other Custom Built Pages in a Sub-directory</a></li> +<li><a name='toc70' href='#sect70'>Markup and Output Examples</a></li> +<li><a name='toc71' href='#sect71'>Markup Examples</a></li> +<li><a name='toc72' href='#sect72'>Sisu Markup Samples</a></li> +<li><a name='toc73' href='#sect73'>Sisu Search - Introduction</a></li> +<li><a name='toc74' href='#sect74'>Sql</a></li> +<li><a name='toc75' href='#sect75'>Populating Sql Type Databases</a></li> +<li><a name='toc76' href='#sect76'>Postgresql</a></li> +<li><a name='toc77' href='#sect77'>Name</a></li> +<li><a name='toc78' href='#sect78'>Description</a></li> +<li><a name='toc79' href='#sect79'>Synopsis</a></li> +<li><a name='toc80' href='#sect80'>Commands</a></li> +<li><a name='toc81' href='#sect81'>Create and Destroy Database</a></li> +<li><a name='toc82' href='#sect82'>Import and Remove Documents</a></li> +<li><a name='toc83' href='#sect83'>Sqlite</a></li> +<li><a name='toc84' href='#sect84'>Name</a></li> +<li><a name='toc85' href='#sect85'>Description</a></li> +<li><a name='toc86' href='#sect86'>Synopsis</a></li> +<li><a name='toc87' href='#sect87'>Commands</a></li> +<li><a name='toc88' href='#sect88'>Create and Destroy Database</a></li> +<li><a name='toc89' href='#sect89'>Import and Remove Documents</a></li> +<li><a name='toc90' href='#sect90'>Introduction</a></li> +<li><a name='toc91' href='#sect91'>Search - Database Frontend Sample, Utilising Database and Sisu Features,</a></li> +<li><a name='toc92' href='#sect92'>Search Form</a></li> +<li><a name='toc93' href='#sect93'>Sisu_webrick</a></li> +<li><a name='toc94' href='#sect94'>Name</a></li> +<li><a name='toc95' href='#sect95'>Synopsis</a></li> +<li><a name='toc96' href='#sect96'>Description</a></li> +<li><a name='toc97' href='#sect97'>Summary of Man Page</a></li> +<li><a name='toc98' href='#sect98'>Document Processing Command Flags</a></li> +<li><a name='toc99' href='#sect99'>Summary of Features</a></li> +<li><a name='toc100' href='#sect100'>See Also</a></li> +<li><a name='toc101' href='#sect101'>Homepage</a></li> +<li><a name='toc102' href='#sect102'>Source</a></li> +<li><a name='toc103' href='#sect103'>Author</a></li> +</ul> +</body> +</html> |