sisu packaging notes
authorRalph Amissah <ralph@amissah.com>
Tue, 7 Apr 2015 02:51:12 +0000 (22:51 -0400)
committerRalph Amissah <ralph@amissah.com>
Thu, 9 Apr 2015 03:05:39 +0000 (23:05 -0400)
data/doc/sisu/org/sisu.org
data/doc/sisu/org/sisu_packaging.org [new file with mode: 0644]

index ef566d3c79e75f61d068571d4c510a2f18fb8249..3ea2f44628e7a061cd805bf8960402fe28b20c5a 100644 (file)
@@ -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 (file)
index 0000000..3ef53fe
--- /dev/null
@@ -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