diff options
Diffstat (limited to 'data/doc/sisu')
| -rw-r--r-- | data/doc/sisu/org/sisu.org | 67 | ||||
| -rw-r--r-- | data/doc/sisu/org/sisu_packaging.org | 269 |
2 files changed, 303 insertions, 33 deletions
diff --git a/data/doc/sisu/org/sisu.org b/data/doc/sisu/org/sisu.org index ef566d3c..3ea2f446 100644 --- a/data/doc/sisu/org/sisu.org +++ b/data/doc/sisu/org/sisu.org @@ -3,14 +3,12 @@ (emacs:evil mode gifts a "vim" of enticing "alternative" powers! ;) (vim, my _editor_ of choice also in the emacs environment :) -* General - -** what is sisu? +* What is SiSU? Multiple output formats with a nod to the strengths of each output format and the ability to cite text easily across output formats. -*** debian/control desc +** debian/control desc documents - structuring, publishing in multiple formats and search SiSU is a lightweight markup based, command line oriented, document @@ -56,7 +54,7 @@ documents - structuring, publishing in multiple formats and search SiSU works well under po4a translation management, for which an administrative sample Rakefile is provided with sisu_manual under markup-samples. j -*** take two +** take two SiSU may be regarded as an open access document publishing platform, applicable to a modest but substantial domain of documents (typically law and literature, @@ -217,7 +215,7 @@ Development work is on Linux and the easiest way to install it is through the Debian Linux package as this takes care of optional external dependencies such as XeTeX for PDF output and Postgresql or Sqlite for search. -*** multiple document formats +** multiple document formats Text can be represented in multiple output formats with different characteristics that are (or may be) regarded as strengths/advantages and @@ -232,23 +230,23 @@ formats. For citation across output formats, SiSU uses object citation numbers. -*** document structure and document objects +** document structure and document objects SiSU breaks marked up text into document structure and objects Document structure being the document heading hierarchy (having separated out the document header). -**** What are document objects? +*** What are document objects? An object is an identified meaningful unit of a document, most commonly a paragraph of text, but also for example a table, code block, verse or image. SiSU tracks these substantive document units as document objects (and their relationship to the document structure). -*** object citation numbers +** object citation numbers -**** What are object citation numbers? +*** What are object citation numbers? An object citation number is a sequential number assigned to a document object. @@ -259,7 +257,7 @@ across various digital outputs whether paper, screen, or database oriented, prepared appropriately. This numbering system can be used to reference content across output types. -**** Why might I want object citation numbering? +*** Why might I want object citation numbering? The ability to cite and quickly locate text can be invaluable if not essential. (whether for instruction or discussion). @@ -300,7 +298,7 @@ foreign language counterpart some detail of the text, or, how do I point my foreign language counterpart to the text I would like to bring to his attention. -*** "Granular" Search +** "Granular" Search Of interest is the ease of streaming documents to a relational database, at an object (roughly paragraph) level and the potential for increased precision in @@ -308,7 +306,7 @@ the presentation of matches that results thereby. The ability to serialize html, LaTeX, XML, SQL, (whatever) is also inherent in / incidental to the design. -*** Summary +** Summary SiSU information Structuring Universe Structured information, Serialized Units <www.sisudoc.org> or <www.jus.uio.no/sisu/> software for electronic texts, document collections, @@ -317,7 +315,7 @@ system (shared text citation numbering: "ocn") outputs include: plaintext, html, XHTML, XML, ODF (OpenDocument), EPUB, LaTeX, PDF, SQL (PostgreSQL and SQLite) -*** SiSU Short Description +** SiSU Short Description SiSU is a comprehensive future-resilient electronic document management system. Built-in search capabilities allow you to search across multiple documents and @@ -344,7 +342,7 @@ SiSU is an Open Source project initiated and led by Ralph Amissah <http://lists.sisudoc.org/listinfo/sisu> at <sisu@lists.sisudoc.org>. SiSU is licensed under the GNU General Public License. -**** notes +*** notes For less markup than the most elementary HTML you can have more. SiSU - Structured information, Serialized Units for electronic documents, is an @@ -481,7 +479,7 @@ to PDF, a LaTeX processor like tetex or texlive. as a developers tool it is flexible and extensible -*** description +** description SiSU ("SiSU information Structuring Universe" or "Structured information, Serialized Units"),1 is a Unix command line oriented framework for document @@ -536,8 +534,8 @@ cover a wide range of documents within its use domain have been explored. <http://lists.sisudoc.org/listinfo/sisu> 2010 w3 since October 3 1993 -** Finding -*** source +* Finding SiSU +** source http://git.sisudoc.org/gitweb/ sisu git repo: @@ -546,7 +544,7 @@ http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary sisu-markup-samples git repo: http://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary -*** mailing list +** mailing list sisu at lists.sisudoc.org http://lists.sisudoc.org/listinfo/sisu @@ -557,9 +555,9 @@ http://lists.sisudoc.org/listinfo/sisu <http://search.sisudoc.org/> <http://www.jus.uio.no/sisu> -** Installing sisu +* Installation -*** where you take responsibility for having the correct dependencies +** where you take responsibility for having the correct dependencies Provided you have *Ruby*, *SiSU* can be run. @@ -572,12 +570,12 @@ 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. -**** run off the source tarball without installation +*** run off the source tarball without installation RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING) .......................................................... -***** 1. Obtain the latest sisu source +**** 1. Obtain the latest sisu source using git: @@ -614,7 +612,7 @@ or off sisu repos or dget -x http://sisudoc.org/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc -***** 2. Unpack the source +**** 2. Unpack the source Provided you have *Ruby*, *SiSU* can be run without installation straight from the source package directory tree. @@ -631,7 +629,7 @@ 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 (with rake) +*** gem install (with rake) (i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install the gem @@ -673,7 +671,7 @@ For a list of alternative actions you may type: Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50> -**** installation with setup.rb +*** installation with setup.rb this is a three step process, in the root directory of the unpacked *SiSU* as root type: @@ -689,7 +687,7 @@ further information: ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install -*** Debian install +** Debian install *SiSU* is available off the *Debian* archives. It should necessary only to run as root, Using apt-get: @@ -739,9 +737,11 @@ The package is divided into the following components: <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. -** sisu markup :sisu:markup: +** Arch Linux + +* sisu markup :sisu:markup: -*** sisu markup +** sisu markup #% structure - headings, levels * headings (A-D, 1-3) @@ -829,14 +829,15 @@ The package is divided into the following components: #% misc * term & definition -*** syntax hilighting +** syntax hilighting -**** vim +*** vim data/sisu/conf/editor-syntax-etc/vim/ data/sisu/conf/editor-syntax-etc/vim/syntax/sisu.vim -**** emacs +*** emacs data/sisu/conf/editor-syntax-etc/emacs/ data/sisu/conf/editor-syntax-etc/emacs/sisu-mode.el -** todo + +* todo sisu_todo.org diff --git a/data/doc/sisu/org/sisu_packaging.org b/data/doc/sisu/org/sisu_packaging.org new file mode 100644 index 00000000..3ef53fe7 --- /dev/null +++ b/data/doc/sisu/org/sisu_packaging.org @@ -0,0 +1,269 @@ +#+OPTIONS: ^:nil _:nil +Developer Notes, Dependencies + +* description +** short summary: 80 chars +smart text parser for document structuring, multiple format publishing & search +** longer + SiSU is a lightweight markup based, command line oriented, document + structuring, publishing and search framework for document collections. + . + With minimal preparation of a plain-text (UTF-8) file, using sisu markup + syntax in a text editor of your choice, SiSU can generate various document + formats (most of which share a common object numbering system for locating + content), including plain text, HTML, XHTML, XML, EPUB, OpenDocument text + (ODF:ODT), LaTeX, PDF files, and populate an SQL database with objects + (roughly paragraph-sized chunks) so searches may be performed and matches + returned with that degree of granularity. Think being able to finely match + text in documents, using object numbers, across different output formats (and + across languages if you have translations of the same document). Search results + can be an index of documents and object numbers within them, your criteria is + met by these documents at these locations within each document (equally + relevant across different output formats and languages). To be clear (if + obvious) page numbers provide none of this functionality. Object numbering is + particularly suitable for "published" works (finalized texts as opposed to + works that are frequently changed or updated) for which it provides a fixed + means of reference of content. Document outputs can also share provided + semantic meta-data. + . + SiSU also provides concordance files, document content certificates and + manifests of generated output. SiSU provides the means to make book indexes + that make use of its object numbering. + . + A vim syntax highlighting file and an ftplugin with folds for sisu markup is + provided. Vim 7 includes syntax highlighting for SiSU. Some syntax hilighting + is also available for Emacs and a few other editors. + . + Dependencies for various features are taken care of in sisu related packages. + The package sisu-complete installs the whole of SiSU. + . + Additional document markup samples are provided in the package + sisu-markup-samples which is found in the non-free archive. The licenses for + the substantive content of the marked up documents provided is that provided + by the author or original publisher. + . + SiSU uses utf-8 & parses left to right. Currently supported languages: + am bg bn br ca cs cy da de el en eo es et eu fi fr ga gl he hi hr hy ia is it + ja ko la lo lt lv ml mr nl nn no oc pl pt pt_BR ro ru sa se sk sl sq sr sv ta + te th tk tr uk ur us vi zh (see XeTeX polyglossia & cjk) + . + SiSU works well under po4a translation management, for which an administrative + sample Rakefile is provided with sisu_manual under markup-samples. +* Generic Dependencies +** source +git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream +*** full source +git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream + +** an install method + +$ qi setup --bin --lib --share --dryrun +$ sudo ./qi setup --bin --lib --share + +$ qi setup --bin --lib --share --conf --data --dryrun +$ sudo ./qi setup --bin --lib --share --conf --data + +$ qi setup --all --dryrun +$ sudo ./qi setup --all dryrun + +** minimal + needed for +---------------------- +ruby all, provides outputs text, html +xz sisupod +zip unzip epub & odt + +*** images +imagemagick | graphicsmagick +ruby-rmagick ? + +** special requirements + +*** pdf + +texlive +texlive-cjk +texlive-fonts ? +texlive-latex ? + +.sty (texpdf_format.rb) + +alltt.sty +amssymb.sty +babel.sty +boites.sty +color.sty +endnotes.sty +fancyhdr.sty +fontspec.sty +footmisc.sty +graphicx.sty +inputenc.sty +listings.sty +longtable.sty +manyfoot.sty +multicol.sty +parskip.sty +polyglossia.sty +soul.sty +textcomp.sty +thumbpdf.sty +titlepic.sty +ucs.sty +ulem.sty +url.sty +xetex.sty +xltxtra.sty +xunicode.sty + +*** sql db +**** sqlite3 + +sqlite3 +ruby-sqlite3 + +ruby-fcgi (fast-cgi) +httpd + +**** postgresql + +postgresql +ruby-pg + +ruby-fcgi (fast-cgi) +httpd + +*** qr codes + +qrencode + +*** maintenance/installation +ruby-thor | rake + +ruby-thor +rake + +* Debian Dependencies + +** source +git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch debian/sid + +** debian/control (extract) + +Package: sisu +Depends: ${misc:Depends}, ruby | ruby-interpreter, rsync, unzip, zip, xz-utils +Recommends: + sisu-pdf, sisu-sqlite, sisu-postgresql, imagemagick | graphicsmagick, keychain, + openssh-client | lsh-client, openssl, po4a, qrencode, rake, ruby-rmagick, + ruby-thor, tidy, tree, vim-addon-manager +Suggests: sisu-markup-samples, lv, calibre, pinfo, poedit, texinfo, trang + +Package: sisu-complete +Depends: + ${misc:Depends}, sisu (= ${source:Version}), sisu-pdf (= ${source:Version}), + sisu-postgresql (= ${source:Version}), sisu-sqlite (= ${source:Version}), + imagemagick | graphicsmagick, openssl, qrencode, ruby-thor, tree +Suggests: sisu-markup-samples + +Package: sisu-pdf +Depends: + ${misc:Depends}, 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: + ${misc:Depends}, sisu (= ${source:Version}), + postgresql, ruby-pg, ruby-fcgi | libfcgi-ruby +Suggests: fcgiwrap, httpd, postgresql-contrib + +Package: sisu-sqlite +Depends: + ${misc:Depends}, sisu (= ${source:Version}), + sqlite3, ruby-sqlite3, ruby-fcgi | libfcgi-ruby +Suggests: fcgiwrap, httpd + +* Arch Linux Dependencies + +** source + +sisu-git + +full clone is more than is needed, so is limiting the branch + +git clone --branch upstream git://git.sisudoc.org/git/code/sisu.git + +try get a shallow clone that contains the last tag for git describe source version info + +git clone --depth 1 --branch upstream git://git.sisudoc.org/git/code/sisu.git +git clone --depth 1 --branch archlinux git://git.sisudoc.org/git/code/sisu.git + +git clone --depth 1 --no-single-branch --branch upstream \ + git://git.sisudoc.org/git/code/sisu.git + +*** git describe, source version +git describe --long --tags | sed 's/^sisu_//;s/\([^-]*-g\)/r\1/;s/-/./g' +git describe --long --tags | sed 's/^[a-z_-]\+//;s/\([^-]*-g\)/r\1/;s/-/./g' +git describe --long --tags | \ + sed 's/^[a-z_-]\+\([0-9.]\+\)/\1/;s/\([^-]*-g\)/r\1/;s/-/./g' + +needs more than a shallow clone of depth 1 + +** pacman install + +sudo pacman -S ruby \ + zip unzip xy + +sudo pacman -S ruby \ + texlive-core texlive-latexextra texlive-fontsextra texlive-langcjk + +sudo pacman -S ruby \ + sqlite postgresql + +# issue with ruby-pg ruby-sqlite ruby-fcgi + +** interpreter + ruby + +** compression tools (epub, odf:odt, sisupod) + zip unzip + xy + +** texlive (pdf) +sudo pacman -S texlive-core texlive-latexextra +sudo pacman -S texlive-core texlive-latexextra texlive-fontsextra texlive-langcjk + +texlive-core extra/texlive-core +texlive-fontsextra extra/texlive-fontsextra +texlive-langcjk extra/texlive-langcjk + +*** .sty (called from texpdf_format.rb) +alltt.sty extra/texlive-core +amssymb.sty extra/texlive-core +babel.sty extra/texlive-core +boites.sty extra/texlive-latexextra +color.sty extra/texlive-core +endnotes.sty extra/texlive-latexextra +fancyhdr.sty extra/texlive-core +fontspec.sty extra/texlive-core +footmisc.sty extra/texlive-latexextra +graphicx.sty extra/texlive-core +inputenc.sty extra/texlive-core +listings.sty extra/texlive-core +longtable.sty extra/texlive-core +manyfoot.sty extra/texlive-latexextra +multicol.sty extra/texlive-core +parskip.sty extra/texlive-core +polyglossia.sty extra/texlive-core +soul.sty extra/texlive-latexextra +textcomp.sty extra/texlive-core +thumbpdf.sty extra/texlive-core +titlepic.sty extra/texlive-latexextra +ucs.sty extra/texlive-latexextra +ulem.sty extra/texlive-core +url.sty extra/texlive-core +xetex.sty ?? +xltxtra.sty extra/texlive-core +xunicode.sty extra/texlive-core |