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