diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 2421 |
1 files changed, 0 insertions, 2421 deletions
diff --git a/README.txt b/README.txt deleted file mode 100644 index 6c5fe255..00000000 --- a/README.txt +++ /dev/null @@ -1,2421 +0,0 @@ -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 |