diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 2421 |
1 files changed, 2421 insertions, 0 deletions
diff --git a/README.txt b/README.txt new file mode 100644 index 00000000..6c5fe255 --- /dev/null +++ b/README.txt @@ -0,0 +1,2421 @@ +SISU - README +============= + +INTRODUCTION +************ + +INTRODUCTION - WHAT IS SISU? +---------------------------- + +*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. + +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. + +Outputs share a common citation numbering system, associated with text objects +and any semantic meta-data provided about the document. + +*SiSU* also provides concordance files, document content certificates and +manifests of generated output. Book indexes may be made. + +Some document markup samples are provided in the package sisu -markup-samples. + +Homepages: +* <http://www.sisudoc.org/> +* <http://www.jus.uio.no/sisu> + +INSTALL OR RUN WITHOUT INSTALLATION +*********************************** + +SOURCE TREE +----------- + +RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING) +.......................................................... + +Download & unpack the latest source tarball + +or + +Git clone the latest source, to clone the latest source without the repo +history: + +git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream + +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) + +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. + +GEM INSTALL +........... + +Gem install, you need to: + +(i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install +the gem + + +---------------------------------------- + +GEM INSTALL WITH QI (QUICK INSTALL) SCRIPT +.......................................... + +(This requires that ruby -thor is installed). + +qi (quick install) can go through the steps required to install the gem: + + qi gem --create --build --install --stable + +or + + qi gem --create --build --install --unstable + + +---------------------------------------- + +GEM INSTALL WITH RAKE +..................... + +Provided you have ruby & rake, this can be done with the single command: + + rake gem_create_build_install # (to build and install, alias gemcbi) + +for individual steps (create, build, install) see rake options, rake -T to +specify sisu version for sisu installed via gem + +For a list of alternative actions you may type: + + rake help + + rake -T + +Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50> + + +---------------------------------------- + +MISC GEM +........ + +gem search sisu + + sisu _7.0.0_ --version + + sisu _7.0.0_ --version + +to uninstall sisu installed via gem + + sudo gem uninstall --verbose sisu + +DIRECT INSTALLATION WITH QI (QUICK INSTALL) SCRIPT +.................................................. + +(This requires that ruby -thor is installed). + +Root will be requested as required: + + qi setup --bin --lib --conf --data --share --man + +or + + qi setup --all + +You may wish to do a dryrun to see where files would be installed without +copying them, to do so add the flag --dryrun + +INSTALLATION WITH SETUP.RB +.......................... + +It should also be possible to install sisu using setup.rb + +this is a three step process, in the root directory of the unpacked *SiSU* as +root type: + +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> + + ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install + +UNIX/LINUX DISTRIBUTION +----------------------- + +A distribution install should take care of the dependencies of sisu for +producing various outputs. + +DEBIAN +...... + +*SiSU* is available off the *Debian* archives. It should necessary only to run +as root, Using apt-get: + + apt-get update + + apt get install sisu-complete + +(all sisu dependencies should be taken care of) + +If there are newer versions of *SiSU* upstream, they will be available by +adding the following to your sources list /etc/apt/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 + +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. + +*SiSU* is developed on *Debian*, and packages are available for *Debian* that +take care of the dependencies encountered on installation. + +The package is divided into the following components: + + *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 + + *sisu-complete*, a dummy package that installs the whole of greater sisu as + described below, apart from sisu -examples + + *sisu-pdf*, dependencies used by sisu to produce pdf from /LaTeX/ generated + + *sisu-postgresql*, dependencies used by sisu to populate postgresql database + (further configuration is necessary) + + *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 +................................. + +*-[0-9] [filename/wildcard]* +see --act + +*--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. + +*--act[s0-9] [filename/wildcard]* +--act0 to --act9 configurable shortcuts for multiple flags, -0 to -9 synonyms, +configure in sisurc.yml; sisu default action on a specified file where no flag +is provided is --act0; --act or --acts for information on current actions +ascribed to --act0 to --act9 + +*--asciidoc [filename/wildcard]* +asciidoc, smart text (not available) + +*-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. + +*-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 [filename/wildcard/url]* +see --docbook + +*--dal [filename/wildcard/url]* +(abstract objects, document abstraction renamed abstract objects in sisu5) see +--ao + +*--delete [filename/wildcard]* +see --zap + +*--digests [filename/wildcard/url]* +document digest or document content certificate ( DCC ) as sha 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). --digests -V for verbose digest output to +screen. + +*--docbook [filename/wildcard/url]* +docbook xml + +*--dom [filename/wildcard/url]* +see --xml-dom + +*--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 + +*--errors-as-warnings* +override stop processing on error. Alias --no-stop + +*--exc-** +exclude output feature, overrides configuration settings --exc-numbering, see +--exc-ocn; --exc-ocn, (exclude "object citation numbering", (switches off +object citation numbers), 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 xml (not available) + +*--find [optional string part of filename]* +see --glob + +*-G [optional string part of filename]* +see --glob + +*-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]* +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 -G, -f, --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. + +*--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. + +*--manifest [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. + +*--manpage [filename/wildcard]* +produces man page of file, not suitable for all outputs. Alias -i + +*--markdown [filename/wildcard/url]* +markdown smart text (not available) + +*--monolingual* +see --i18n-* + +*--multilingual* +see --i18n-* + +*-N [filename/wildcard/url]* +see --digests + +*-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-* + +*--no-stop* +override stop processing on error. Alias --erros-as-warnings + +*--numbering* +turn on "object citation numbers". See --inc-ocn and --exc-ocn + +*-o [filename/wildcard/url]* +see --odt + +*--ocn* +"object citation numbers". 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: --pg-createdb; --pg-create; --pg-dropall; --pg-import [filename]; +--pg-update [filename]; --pg-remove [filename]; see database section below. + +*--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). + +*--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 (not available) + +*--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-(pg|sqlite)]* +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: --db-user='www-data'. 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 + +*--sax [filename/wildcard/url]* +see --xml-sax + +*--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 + +*--sha256* +set hash digest where used to sha256 + +*--sha512* +set hash digest where used to sha512 + +*--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: --sqlite-createdb; +--sqlite-create; --sqlite-dropall; --sqlite-import [filename]; --sqlite-update +[filename]; --sqlite-remove [filename]); see database section below. + +*--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 (not available) + +*--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-asciidoc [filename/wildcard]* +see --asciidoc + +*--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 + +*--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 + +*--very-verbose [filename/wildcard]* +provides more verbose output of what is being generated. See --verbose. Alias +-V + +*--version* +sisu version + +*-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]* +see --manifest + +*-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* + +*--pg or --pgsql* set for /PostgreSQL/ *--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. + +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. + +MARKUP RULES, DOCUMENT STRUCTURE AND METADATA REQUIREMENTS +.......................................................... + +minimal content/structure requirement: + +[metadata] + +A~ (level A [title]) + +1~ (at least one level 1 [segment/(chapter)]) + +structure rules (document heirarchy, heading levels): + +there are two sets of heading levels ABCD (title & parts if any) and 123 +(segment & subsegments if any) + +sisu has the fllowing levels: + +A~ [title] . + required (== 1) followed by B~ or 1~ +B~ [part] * + followed by C~ or 1~ +C~ [subpart] * + followed by D~ or 1~ +D~ [subsubpart] * + followed by 1~ +1~ [segment (chapter)] + + required (>= 1) followed by text or 2~ +text * + followed by more text or 1~, 2~ + or relevant part *() +2~ [subsegment] * + followed by text or 3~ +text * + followed by more text or 1~, 2~ or 3~ + or relevant part, see *() +3~ [subsubsegment] * + followed by text +text * + followed by more text or 1~, 2~ or 3~ or relevant part, see *() + +*(B~ if none other used; + if C~ is last used: C~ or B~; + if D~ is used: D~, C~ or B~) + +* level A~ is the tile and is mandatory +* there can only be one level A~ +* heading levels BCD, are optional and there may be several of each + (where all three are used corresponding to e.g. Book Part Section) + * sublevels that are used must follow each other sequentially + (alphabetically), +* heading levels A~ B~ C~ D~ are followed by other heading levels rather + than substantive text + which may be the subsequent sequential (alphabetic) heading part level + or a heading (segment) level 1~ +* there must be at least one heading (segment) level 1~ + (the level on which the text is segmented, in a book would correspond + to the Chapter level) +* additional heading levels 1~ 2~ 3~ are optional and there may be several + of each +* heading levels 1~ 2~ 3~ are followed by text (which may be followed by + the same heading level) + and/or the next lower numeric heading level (followed by text) + or indeed return to the relevant part level + (as a corollary to the rules above substantive text/ content + must be preceded by a level 1~ (2~ or 3~) heading) + +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] + +@links: + { SiSU Homepage }http://www.sisudoc.org/ + { SiSU Manual }http://www.sisudoc.org/sisu/sisu_manual/ + { Book Samples & Markup Examples }http://www.jus.uio.no/sisu/SiSU/examples.html + { SiSU Download }http://www.jus.uio.no/sisu/SiSU/download.html + { SiSU Changelog }http://www.jus.uio.no/sisu/SiSU/changelog.html + { SiSU Git repo }http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary + { SiSU List Archives }http://lists.sisudoc.org/pipermail/sisu/ + { SiSU @ Debian }http://packages.qa.debian.org/s/sisu.html + { SiSU Project @ Debian }http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org + { SiSU @ Wikipedia }http://en.wikipedia.org/wiki/SiSU + +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 + +_9 indent paragraph nine steps + +*resulting output:* + +ordinary paragraph + + 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 [3sS]⌡viral_spiral.david_bollier.sst + +GROUPED TEXT / BLOCKED TEXT +........................... + +There are two markup syntaxes for blocked text, using curly braces or using +tics + + +---------------------------------------- + +BLOCKED TEXT CURLY BRACE SYNTAX +............................... + +at the start of a line on its own use name of block type with an opening curly +brace, follow with the content of the block, and close with a closing curly +brace and the name of the block type, e.g. + +code{ +this is a code block + +}code + +poem{ + +this here is a poem + +}poem + + +---------------------------------------- + +BLOCKED TEXT TIC SYNTAX +....................... + +``` code +this is a code block + +``` + +``` poem + +this here is a poem + +``` + +start a line with three backtics, a space followed by the name of the name of +block type, follow with the content of the block, and close with three back +ticks on a line of their own, e.g. + + +---------------------------------------- + +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:*[^9] + +!_ 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 =\= breaks the page, starts a new page. + +page break -\- 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: + +-\\- + +page (break) new: + +=\\= + +page (break) line across page (dividing paragraphs): + +-..- + +BIBLIOGRAPHY / REFERENCES +......................... + +There are three ways to prepare a bibliography using sisu (which are mutually +exclusive): (i) manually preparing and marking up as regular text in sisu a +list of references, this is treated as a regular document segment (and placed +before endnotes if any); (ii) preparing a bibliography, marking a heading level +1~!biblio (note the exclamation mark) and preparing a bibliography using +various metadata tags including for author: title: year: a list of which is +provided below, or; (iii) as an assistance in preparing a bibliography, marking +a heading level 1~!biblio and tagging citations within footnotes for inclusion, +identifying citations and having a parser attempt to extract them and build a +bibliography of the citations provided. + +For the heading/section sequence: endnotes, bibliography then book index to +occur, the name biblio or bibliography must be given to the bibliography +section, like so: + +1~!biblio~ [Note: heading marker::required title missing] + + +---------------------------------------- + +A MARKUP TAGGED METADATA BIBLIOGRAPHY SECTION +............................................. + +Here instead of writing your full citations directly in footnotes, each time +you have new material to cite, you add it to your bibliography section (if it +has not been added yet) providing the information you need against an available +list of tags (provided below). + +The required tags are au: ti: and year: [^10] an short quick example might be +as follows: + +1~!biblio~ [Note: heading marker::required title missing] + +au: von Hippel, E. +ti: Perspective: User Toolkits for Innovation +lng: (language) +jo: Journal of Product Innovation Management +vo: 18 +ed: (editor) +yr: 2001 +note: +sn: Hippel, /{User Toolkits}/ (2001) +id: vHippel_2001 +% form: + +au: Benkler, Yochai +ti: The Wealth of Networks +st: How Social Production Transforms Markets and Freedom +lng: (language) +pb: Harvard University Press +edn: (edition) +yr: 2006 +pl: U.S. +url: http://cyber.law.harvard.edu/wealth_of_networks/Main_Page +note: +sn: Benkler, /{Wealth of Networks}/ (2006) +id: Benkler2006 + +au: Quixote, Don; Panza, Sancho +ti: Taming Windmills, Keeping True +jo: Imaginary Journal +yr: 1605 +url: https://en.wikipedia.org/wiki/Don_Quixote +note: made up to provide an example of author markup for an article with two authors +sn: Quixote & Panza, /{Taming Windmills}/ (1605) +id: quixote1605 + +Note that the section name !biblio (or !bibliography) is required for the +bibliography to be treated specially as such, and placed after the +auto-generated endnote section. + +Using this method, work goes into preparing the bibliography, the tags author +or editor, year and title are required and will be used to sort the +bibliography that is placed under the Bibliography section + +The metadata tags may include shortname (sn:) and id, if provided, which are +used for substitution within text. Every time the given id is found within the +text it will be replaced by the given short title of the work (it is for this +reason the short title has sisu markup to italicize the title), it should work +with any page numbers to be added, the short title should be one that can +easily be used to look up the full description in the bibliography. + +The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~ + +would be presented as: + +Quixote and Panza, /Taming Windmills/ (1605), pp 1000 - 1001 also, Benkler, +/Wealth of Networks/, (2006) p 1 or rather[^11] + +au: author Surname, FirstNames (if multiple semi-colon separator) + (required unless editor to be used instead) +ti: title (required) +st: subtitle +jo: journal +vo: volume +ed: editor (required if author not provided) +tr: translator +src: source (generic field where others are not appropriate) +in: in (like src) +pl: place/location (state, country) +pb: publisher +edn: edition +yr: year (yyyy or yyyy-mm or yyyy-mm-dd) (required) +pg: pages +url: http://url +note: note +id: create_short_identifier e.g. authorSurnameYear + (used in substitutions: when found within text will be + replaced by the short name provided) +sn: short name e.g. Author, /{short title}/, Year + (used in substitutions: when an id is found within text + the short name will be used to replace it) + + +---------------------------------------- + +TAGGING CITATIONS FOR INCLUSION IN THE BIBLIOGRAPHY +................................................... + +Here whenever you make a citation that you wish be included in the +bibliography, you tag the citation as such using special delimiters (which are +subsequently removed from the final text produced by sisu) + +Here you would write something like the following, either in regular text or a +footnote + +See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :. + +*SiSU* will parse for a number of patterns within the delimiters to try make +out the authors, title, date etc. and from that create a Bibliography. This is +more limited than the previously described method of preparing a tagged +bibliography, and using an id within text to identify the work, which also +lends itself to greater consistency. + +GLOSSARY +........ + +Using the section name 1~!glossary results in the Glossary being treated +specially as such, and placed after the auto-generated endnote section (before +the bibliography/list of references if there is one). + +The Glossary is ordinary text marked up in a manner deemed suitable for that +purpose. e.g. with the term in bold, possibly with a hanging indent. + +1~!glossary~ [Note: heading marker::required title missing] + +_0_1 *{GPL}* An abbreviation that stands for "General Purpose License." ... + +_0_1 [provide your list of terms and definitions] + +In the given example the first line is not indented subsequent lines are by one +level, and the term to be defined is in bold text. + +BOOK INDEX +.......... + +To make an index append to paragraph the book index term relates to it, using +an equal sign and curly braces. + +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. + + Paragraph containing main term and sub-term. + ={Main term:sub-term} + +The index syntax starts on a new line, but there should not be an empty line +between paragraph and index markup. + +The structure of the resulting index would be: + + Main term, 1 + sub-term, 1 + +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. + + Paragraph containing main term, second term and sub-term. + ={first term; second term: sub-term} + +The structure of the resulting index would be: + + First term, 1, + Second term, 1, + sub-term, 1 + +If multiple sub-terms appear under one paragraph, they are separated under the +main term heading from each other by a pipe symbol. + + Paragraph containing main term, second term and sub-term. + ={Main term: + sub-term+2|second sub-term; + Another term + } + + A paragraph that continues discussion of the first sub-term + +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: + + Main term, 1, + sub-term, 1-3, + second sub-term, 1, + Another term, 1 + +COMPOSITE DOCUMENTS MARKUP +-------------------------- + +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* + +basic markup for importing a document into a master document + +<< filename1.sst + +<< filename2.ssi + +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. + +SUBSTITUTIONS +------------- + +*markup example:* + +The current Debian is ${debian_stable} the next debian will be ${debian_testing} + +Configure substitution in _sisu/sisu_document_make + +@make: +:substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*' + +*resulting output:* + +The current *Debian* is *Jessie* the next debian will be *Stretch* + +Configure substitution in _sisu/sisu_document_make + + +---------------------------------------- + + +---------------------------------------- + + +---------------------------------------- + + + [1]: <http://packages.qa.debian.org/s/sisu.html> + + [2]: from the *Debian* control file + + [*1]: square brackets + + [*2]: square brackets + + [+1]: square brackets + + [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. + + [4]: files should be prepared using /UTF-8/ character encoding + + [5]: a footnote or endnote + + [6]: self contained endnote marker & endnote in one + + [*]: unnumbered asterisk footnote/endnote, insert multiple asterisks if required + + [**]: another unnumbered asterisk footnote/endnote + + [*3]: editors notes, numbered asterisk footnote/endnote series + + [+2]: editors notes, numbered plus symbol footnote/endnote series + + [7]: <http://www.sisudoc.org/> + + [8]: <http://www.ruby-lang.org/en/> + + [9]: Table from the Wealth of Networks by Yochai Benkler + + http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler + + [10]: for which you may alternatively use the full form author: title: and year: + + [11]: Quixote and Panza, /Taming Windmills/ (1605), pp 1000 - 1001 also, Benkler, + /Wealth of Networks/ (2006), p 1 + +============================================================================== + + Title: SiSU - README + + Creator: Ralph Amissah + + Rights: Copyright: 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, ASCII text, with very long lines + + Source digest: SHA256(README.ssm.sst)= + 2084f396c985a9d784d66fd6219c6c4d6b6a7b1d53619f57012641ccaa8b1c5d + + Generated by: Generated by: SiSU 7.0.1_pre_rel of 2015w18/2 (2015-05-05) + + Ruby version: ruby 2.1.5p273 (2014-11-13) [x86_64-linux-gnu] + + Document (ao) last generated: 2015-05-12 16:33:24 -0400 + +============================================================================== + + +plaintext (plain text): + http://niu/manual/en/txt/README.txt + +Other versions of this document: + +manifest: + http://niu/manual/en/manifest/README.manifest.html + +at: + http://niu/manual + + + +* Generated by: SiSU 7.0.1_pre_rel of 2015w18/2 (2015-05-05) +* Ruby version: ruby 2.1.5p273 (2014-11-13) [x86_64-linux-gnu] +* Last Generated on: 2015-05-12 16:33:26 -0400 +* SiSU www.sisudoc.org |