aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2015-04-06 22:51:12 -0400
committerRalph Amissah <ralph@amissah.com>2015-04-08 23:05:39 -0400
commit096c8888f11c857f97ee4da9963221666de9205b (patch)
treee63bade5a7f6f00af84547886120825f57c5e769
parentsisu.org, prevent subscripting (by underscore) mangles file paths (diff)
sisu packaging notes
-rw-r--r--data/doc/sisu/org/sisu.org67
-rw-r--r--data/doc/sisu/org/sisu_packaging.org269
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