diff options
Diffstat (limited to 'org/sisu_build.org')
| -rw-r--r-- | org/sisu_build.org | 6000 |
1 files changed, 6000 insertions, 0 deletions
diff --git a/org/sisu_build.org b/org/sisu_build.org new file mode 100644 index 00000000..0380a5ee --- /dev/null +++ b/org/sisu_build.org @@ -0,0 +1,6000 @@ +-*- mode: org -*- +#+TITLE: SiSU +#+DESCRIPTION: sisu build +#+FILETAGS: :sisu:build: +#+AUTHOR: Ralph Amissah +#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]] +#+COPYRIGHT: Copyright (C) 2015 - 2020 Ralph Amissah +#+LANGUAGE: en +#+STARTUP: content hideblocks hidestars noindent entitiespretty +#+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil _:nil -:t f:t *:t <:t +#+PROPERTY: header-args :exports code +#+PROPERTY: header-args+ :noweb yes +#+PROPERTY: header-args+ :eval no +#+PROPERTY: header-args+ :results no +#+PROPERTY: header-args+ :cache no +#+PROPERTY: header-args+ :padline no + +* sisu git CHANGELOG TODO +** git used TODO + +#+BEGIN_SRC sh +CHL="data/doc/sisu/CHANGELOG" +git log --pretty=format:'-_-%+s %+as %ae%+h%d%+b' --no-merges \ +| sed "/^\\s*$/d" | sed "s/^\([ ]\)*\*/\1-/" | sed "s/ \+$//" | sed "s/^-_-$//" \ +> ${CHL} +#+END_SRC + +** alt + +#+BEGIN_SRC sh +CHL="data/doc/sisu/CHANGELOG" +git log --pretty=format:"-_-_%+s %+as %ae%+h%d%+b" --no-merges \ +> ${CHL} && sed -i '/^$/d; s/^\([ ]\)*\*/\1-/; s/ \+$//; s/^-_-_//' ${CHL} +#+END_SRC + +** +considered+ + +#+BEGIN_SRC sh +LOG_0="changelog_0_" +git log --decorate --sparse --date=short --no-merges --abbrev-commit --format=medium \ +> ${LOG_0} && sed -i 's/^[ ]\+$//; /^$/d' ${LOG_0} +#+END_SRC + +#+BEGIN_SRC sh +LOG_1="changelog_1_" +git log --pretty=format:"%h %as - %s%d <%ae> %+b" --no-merges \ +> ${LOG_1} && sed -i '/^$/d; s/^\([ ]\)*\*/\1-/; s/ \+$//' ${LOG_1} +#+END_SRC + +#+BEGIN_SRC sh +LOG_2="data/doc/sisu/CHANGELOG_1_" +git log --pretty=format:"%h %ad - %s%d [%an]" --graph --date=short --no-merges > ${LOG_2} +#+END_SRC + +* sisu version TODO + +#+BEGIN_SRC ruby :tangle ../setup/sisu_version.rb +#% constants +module SiSUversion + SiSU_version = '7.2.1' +end +module Dev + GPGpubKey = '1BB4B289' +end +#+END_SRC + +* +makefile+ :makefile: + +#+BEGIN_SRC makefile :NO-tangle ../makefile +#+END_SRC + +* qi (quick install) +** bin + +#+BEGIN_SRC ruby :tangle ../qi :tangle-mode (identity #o755) :shebang #!/usr/bin/env ruby +=begin + +- Description: + +- Homepage: <http://www.jus.uio.no/sisu/SiSU> + <http://search.sisudoc.org> +- Download: <http://www.jus.uio.no/sisu/download> + +- Copyright: (C) 2015, 2020 Ralph Amissah + +- License: + +- Ralph Amissah <ralph.amissah@gmail.com> + +=end +#% manual settings, edit/update as required (note current default settings are obtained from sisu version yml file) +begin + require 'thor' +rescue LoadError + puts 'thor (package ruby-thor) not found' +end +begin + require './setup/sisu_version' # ./setup/sisu_version.rb + include SiSUversion +rescue LoadError + puts 'this does not appear to be a SiSU development directory' + exit +end +require_relative 'setup/qi_libs' # setup/qi_libs.rb +require 'find' +require 'fileutils' + include FileUtils +require 'pathname' +require 'rbconfig.rb' +require 'yaml' +module SiSUconf + class Configure < Thor + class_option :verbose, :type => :boolean + desc 'setup --all --bin --lib --conf --data --alt --dryrun', + 'setup sisu' + options \ + :all => :boolean, + :bin => :boolean, + :lib => :boolean, + :conf => :boolean, + :data => :boolean, + :share => :boolean, + :man => :boolean, + :vim => :boolean, + :alt => :boolean, + :dryrun => :boolean, + :is => :boolean + def setup + unless options.length >= 1 \ + and not (options[:bin] \ + or options[:lib] \ + or options[:conf] \ + or options[:data] \ + or options[:share] \ + or options[:man] \ + or options[:vim]) + puts 'setup --all --bin --lib --conf --data --share --man --vim' + end + act=(options[:dryrun]) ? (:dryrun) : (:action) + if options[:is] + puts Version_info.version_number_info_stable + end + if not options[:alt] + if options[:all] \ + or options[:bin] + exclude_files=['sisugem'] + Install.setup_find_create( + 'bin', + Project_details.dir.bin, + exclude_files, + act + ) if File.directory?('bin') + end + if options[:all] \ + or options[:lib] + Install.setup_find_create( + 'lib', + Project_details.dir.lib, + act + ) if File.directory?('lib') + end + if options[:all] \ + or options[:conf] + Install.setup_find_create( + 'conf', + Project_details.dir.conf, + act + ) if File.directory?('conf') + end + if options[:all] \ + or options[:data] + Install.setup_find_create( + 'data', + Project_details.dir.data, + act + ) if File.directory?('data') + end + if options[:all] \ + or options[:share] + Install.setup_find_create( + 'data/sisu', + Project_details.dir.share, + act + ) if File.directory?('data/sisu') + end + if options[:all] \ + or options[:man] + Install.setup_find_create( + 'man', + Project_details.dir.man, + act + ) if File.directory?('man') + end + if options[:all] \ + or options[:vim] + Install.setup_find_create( + 'data/vim', + Project_details.dir.vim, + act + ) if File.directory?('data/vim') + end + else + if options[:all] \ + or options[:bin] + Install.setup_find_cp_r( + 'bin', + Project_details.dir.bin, + act + ) if File.directory?('bin') + end + if options[:all] \ + or options[:bin] + Install.setup_find_cp_r( + 'lib', + Project_details.dir.lib, + act + ) if File.directory?('lib') + end + if options[:all] \ + or options[:conf] + Install.setup_find_cp_r( + 'conf', + Project_details.dir.conf, + act + ) if File.directory?('conf') + end + if options[:all] \ + or options[:data] + Install.setup_find_cp_r( + 'data', + Project_details.dir.data, + act + ) if File.directory?('data') + end + if options[:all] \ + or options[:share] + Install.setup_find_cp_r( + 'data/sisu', + Project_details.dir.share, + act + ) if File.directory?('data/sisu') # + end + if options[:all] \ + or options[:man] + Install.setup_find_cp_r( + 'man', + Project_details.dir.man, + act + ) if File.directory?('man') + end + #if options[:all] \ + #or options[:vim] + # Install.setup_find_cp_r('data/vim',"#{Project_details.dir.data}/vim") \ + # if File.directory?('data/vim') + #end + end + end + desc 'pkg', + 'package maintenance tasks, ' \ + + 'of no general interest ' \ + + '(maintainer specific for package maintainer\'s convenience)' + options \ + :open_version=> :boolean, + :version_and_tag_for_release=> :boolean, + :tip => :boolean, + :is => :boolean + def pkg + if options[:is] + puts Version_info.version_number_info_stable + end + if options[:tip] + Package.sequence + end + if options[:open_version] + Version_info::Update.update_documentation + Version_info::Update.update_stable(:pre_release) + Version_info::Update.update_pkgbuild_stable(:pre_release) + Version_info::Update.changelog_header_stable_pre_release + Version_info::Update.changelog_header_commit(:pre_release) + end + if options[:version_and_tag_for_release] + Version_info::Update.update_documentation + Version_info::Update.update_stable(:release) + Version_info::Update.update_pkgbuild_stable(:release) + Version_info::Update.changelog_header_stable + Version_info::Update.changelog_header_commit_tag_upstream(:release) + end + if options.length == 0 + system("#{$called_as} help pkg") + system("#{$called_as} pkg --tip") + end + end + desc 'gem --create --build --install', + 'gem create build and install' + options \ + :create => :boolean, + :build => :boolean, + :install => :boolean, + :git_version_number => :boolean, + :is => :boolean + def gem + if options[:is] + puts Version_info.version_number_info_stable + end + if options[:create] + version=(options[:git_version_number]) \ + ? :version_git + : :version_standard + Gemspecs::Current.create_stable(version) + puts 'created gemspec' \ + if options[:verbose] + end + if options[:build] + Gemspecs::Current.build_stable + puts 'built gem' \ + if options[:verbose] + end + if options[:install] + version=(options[:git_version_number]) \ + ? :version_git + : :version_standard + Gemspecs::Current.install_stable(version) + puts 'installed gem, version: stable' \ + if options[:verbose] + end + unless options.length > 0 + system("#{$called_as} help gem") + end + end + end +end +begin + $called_as,$argv=$0,$* + SiSUconf::Configure.start(ARGV) +rescue +end +__END__ +#+END_SRC + +** qi_lib + +#+BEGIN_SRC ruby :tangle ../setup/qi_libs.rb +require_relative 'sisu_version' +module Project_details + include SiSUversion + def self.name + 'SiSU' + end + def self.summary + 'documents - structuring, publishing in multiple formats & search' + end + def self.description + 'documents - structuring, publishing in multiple formats & search' + end + def self.homepage + 'http://www.sisudoc.org' + end + def self.thor + "ruby-thor files for the installation/setup of #{name}" + end + def self.platform_notice + "[#{name} is for Linux/Unix Platforms]" + end + def self.env + RbConfig::CONFIG + end + def self.host + env['host'] + end + def self.dir + def self.proj + Project_details.name.downcase + end + def self.arch + env['archdir'] + end + def self.sitearch + env['sitearchdir'] + end + def self.bin + env['bindir'] + end + def self.lib + env['sitelibdir'] + end + def self.data + env['datadir'] + end + def self.share + "#{env['datadir']}/sisu" + end + def self.conf + env['sysconfdir'] + end + def self.man + env['mandir'] + end + def self.vim + "#{env['datadir']}/sisu/vim" + end + def self.out + "#{env['localstatedir']}/#{proj}" + end + def self.rubylib + env['LIBRUBYARG_SHARED'] + end + def self.pwd + Dir.pwd #ENV['PWD'] + end + self + end + def self.version + stamp={} + v="#{dir.pwd}/data/sisu/version.yml" + if File.exist?(v) + stamp=YAML::load(File::open(v)) + stamp[:version] + else '' + end + end + def self.system_info + ##{Project_details.platform_notice} + puts <<-WOK + Host + host: #{Project_details.host} + arch: #{Project_details.dir.arch} + sitearch: #{Project_details.dir.sitearch} + Directories for installation + bin: #{Project_details.dir.bin} + lib (site-ruby): #{Project_details.dir.lib}/#{Project_details.dir.proj}/v* + conf [etc]: #{Project_details.dir.conf}/#{Project_details.dir.proj} + data (odf, shared images): #{Project_details.dir.share} + vim (vim syntax, highlighting, ftplugin): #{Project_details.dir.data}/sisu/vim + data (README, version_manifest): #{Project_details.dir.data}/doc/#{Project_details.dir.proj} + man (manual pages): #{Project_details.dir.man} + output: #{Project_details.dir.out} + processing: #{Project_details.dir.out}/processing + www: #{Project_details.dir.out}/www + rubylib: #{Project_details.dir.rubylib} + + WOK + end + def self.gem_env + system("gem env") + end +end +module Utils + def self.answer?(ask) + resp='redo' + print ask + " ['yes', 'no' or 'quit']: " + resp=File.new('/dev/tty').gets.strip #resp=gets.strip + if resp == 'yes' then true + elsif resp == 'no' then false + elsif resp =~/^quit|exit$/ then exit + else puts "[please type: 'yes', 'no' or 'quit']" + answer?(ask) + end + end + def self.default_notice # local help not implemented description incorrect + ans= %{#{Project_details.thor} + Information on alternative actions is available using: + [if ruby-thor is installed:] + "#{$called_as} help") + Default action selected - "install #{Project_details.name}" proceed? } + resp=answer?(ans) + exit unless resp + end + def self.chmod_file(place) + if place =~/\/bin/; File.chmod(0755,place) + else File.chmod(0644,place) + end + end + def self.chmod_util(place) + if place =~/\/bin/; chmod(0755,place) + else chmod(0644,place) + end + end + def self.system_date + `date "+%Y-%m-%d"`.strip + end + def self.system_date_stamp + `date "+%Yw%W/%u"`.strip + end + def self.program_found?(prog) + found=`which #{prog}` #`whereis #{make}` + (found =~/bin\/#{prog}\b/) ? :true : :false + end +end +module Install + #%% using a directory and its mapping + def self.setup_find_create(dir_get,dir_put,exclude_files=['\*'],act) #primary, + begin + Find.find("#{Project_details.dir.pwd}/#{dir_get}") do |f| + stub=f.scan(/#{Project_details.dir.pwd}\/#{dir_get}\/(\S+)/).join + place="#{dir_put}/#{stub}" + action=case + when File.file?(f) + unless f =~/#{exclude_files.join("|")}/ + unless act==:dryrun + cp(f,place) + Utils.chmod_file(place) + end + "-> #{dir_put}/" + end + when File.directory?(f) + if not FileTest.directory?(place) \ + and not act==:dryrun + FileUtils.mkpath(place) + end + "./#{dir_get}/" + else '?' + end + puts "#{action}#{stub}" + end + rescue + puts "\n\n[ are you root? required for install ]" + end + end + def self.setup_find_cp_r(dir_get,dir_put,act) #secondary, using recursive copy + begin + Find.find("#{Project_details.dir.pwd}/#{dir_get}") do |f| + stub=f.scan(/#{Project_details.dir.pwd}\/#{dir_get}\/(\S+)/).join + place="#{dir_put}/#{stub}" + case + when File.file?(f) + unless act==:dryrun + cp_r(f,place) + Utils.chmod_util(place) + else + puts "--> #{place}" + end + when File.directory?(f) + unless FileTest.directory?(place) + unless act==:dryrun + mkdir(place) + else + puts "mkdir -p #{place}" + end + end + end + end + rescue + puts "\n\n[ are you root? required for install ]" + end + end +end +module Version_info + def self.contents(vi,rel=:release) + release=rel ==:pre_release \ + ? '_pre_rel' + : '' + <<-WOK +--- +:project: #{vi[:project]} +:version: #{vi[:version]}#{release} +:date_stamp: #{vi[:date_stamp]} +:date: "#{vi[:date]}" + WOK + end + def self.git_version_extract + if FileTest.file?('/usr/bin/git') + x=`git describe --long --tags 2>&1`.strip. + gsub(/^[a-z_-]*([0-9.]+)/,'\1'). + gsub(/([^-]*-g)/,'r\1'). + gsub(/-/,'.') + x=(x=~/^[0-9]+\.[0-9]+\.[0-9]+\.r[0-9]+\.g[0-9a-f]{7}/) \ + ? x + : nil + else nil + end + end + def self.version_number(vi) + vi[:version] + end + def self.version_number_use(vi) + (git_version_extract.nil?) \ + ? (vi[:version]) + : git_version_extract + end + def self.version_number_info(vi) + (Version_info.version_number_use(vi) != vi[:version_number]) \ + ? (%{#{vi[:version_number]} from git #{Version_info.version_number_use(vi)}}) + : vi[:version_number] + end + def self.version_number_info_stable + vi=Version_info::Current.setting_stable + (Version_info.version_number_use(vi) != vi[:version_number]) \ + ? (%{#{vi[:version_number]} from git #{Version_info.version_number_use(vi)}}) + : vi[:version_number] + end + module Current + def self.yml_file_path + 'data/sisu/version.yml' + end + def self.settings(file) + v="#{Dir.pwd}/#{file}" + if File.exist?(v) + YAML::load(File::open(v)) + else '' + end + end + def self.changelog_file_stable + 'data/doc/sisu/CHANGELOG_v7' + end + def self.file_stable + yml_file_path + end + def self.setting_stable + hsh=settings(file_stable) + hsh[:version_number]=/([0-9]+\.[0-9]+\.[0-9]+)/. + match(hsh[:version])[1] + hsh + end + def self.version_number + Version_info::Current.setting_stable[:version_number] + end + def self.content_stable + Version_info.contents(setting_stable) + end + end + module Next + def self.settings(v) + { + project: "#{Project_details.name}", + version: "#{v}", + date: "#{Utils.system_date}", + date_stamp: "#{Utils.system_date_stamp}", + } + end + def self.setting_stable + settings(SiSU_version) + end + def self.content_stable(rel) + Version_info.contents(setting_stable,rel) + end + end + module Update + def self.version_number(vi) + /([0-9]+\.[0-9]+\.[0-9]+)/.match(vi[:version])[1] + end + def self.version_number_stable + vi=Version_info::Current.setting_stable + /([0-9]+\.[0-9]+\.[0-9]+)/.match(vi[:version])[1] + end + def self.version_info_update_commit(filename,vi_hash_current,vi_content_current,vi_hash_next,vi_content_next) + ans=%{update #{Project_details.name.downcase} version info replacing: + #{vi_hash_current.sort} +with: + #{vi_hash_next.sort} + +#{vi_content_current} +becoming: +#{vi_content_next} +proceed? } + resp=Utils.answer?(ans) + if resp + fn="#{Dir.pwd}/#{filename}" + if File.writable?("#{Dir.pwd}/.") + file_version=File.new(fn,'w+') + file_version << vi_content_next + file_version.close + else + puts %{*WARN* is the file or directory writable? could not create #{filename}} + end + end + end + def self.update_documentation + fn="#{Dir.pwd}/data/doc/sisu/markup-samples/manual/_sisu/sisu_document_make" + if File.file?(fn) \ + and File.writable?(fn) + ver_no_stable=Version_info::Current.setting_stable[:version_number] + debian_stable='Jessie' + debian_testing='Stretch' + sisu_doc_make = IO.readlines(fn) + sisu_doc_make_next=sisu_doc_make.each.map do |line| + line=line.gsub(/(\/$\{sisu_stable\}\/,)'[0-9]+\.[0-9]+\.[0-9]+'/,"\\1'#{ver_no_stable}'"). + gsub(/(\/$\{debian_stable\}\/,)'\*\{[A-Z][a-z]+\}\*'/, + "\\1'*{#{debian_stable}}*'"). + gsub(/(\/$\{debian_testing\}\/,)'\*\{[A-Z][a-z]+\}\*'/, + "\\1'*{#{debian_testing}}*'") + line + end + if sisu_doc_make_next.length == sisu_doc_make.length + sisu_doc_make_file=File.new(fn,'w+') + sisu_doc_make_next.flatten.each do |line| + sisu_doc_make_file << line + end + sisu_doc_make_file.close + else puts "expected changelog arrays to have same length, in: #{pkgbuild.length}, out: #{pkgbuild_next.length}" + end + end + end + def self.update_stable(rel=:release) + version_info_update_commit( + Version_info::Current.file_stable, + Version_info::Current.setting_stable, + Version_info::Current.content_stable, + Version_info::Next.setting_stable, + Version_info::Next.content_stable(rel), + ) + end + def self.update_pkgbuild_stable(rel=:release) + vn=version_number_stable + ans=%{update PKGBUILD version info: +pkgver=#{vn} + +proceed? } + resp=Utils.answer?(ans) + if resp + filename='PKGBUILD_tar_xz' + fn="#{Dir.pwd}/setup/#{filename}" + if File.writable?(fn) + pkgbuild = IO.readlines(fn) + pkgbuild_next=pkgbuild.each.map do |line| + if line =~/^\s*pkgver=/ + line=line.gsub(/^\s*(pkgver=)[0-9.]+/,"\\1#{vn}") + else line + end + end + if pkgbuild.length == pkgbuild_next.length + pkgbuild_file=File.new(fn,'w+') + pkgbuild_next.flatten.each do |line| + pkgbuild_file << line + end + pkgbuild_file.close + else puts "expected changelog arrays to have same length, in: #{pkgbuild.length}, out: #{pkgbuild_next.length}" + end + end + end + end + def self.changelog_header(vi) + vn=version_number(vi) + <<-WOK +- sisu_#{vn}.orig.tar.xz (#{vi[:date]}:#{vi[:date_stamp].gsub(/20\d\dw/,'')}) + http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/sisu_#{vn} + WOK + end + def self.changelog_header_release(filename,ch,vi) + ans=%{update #{Project_details.name.downcase} changelog header, open version: + + #{ch} +proceed? } + resp=Utils.answer?(ans) + if resp + fn="#{Dir.pwd}/#{filename}" + if File.writable?(fn) + changelog_arr_current = IO.readlines(fn) + changelog_arr_next=changelog_arr_current.each.map do |line| + if line =~/^\*\s+sisu_[0-9]+\.[0-9]+\.[0-9]+(?:_pre_rel)?\.orig\.tar\.xz \(Open commit window: [0-9]{4}-[0-9]{2}-[0-9]{2}; Pre-Release\)$/ + "* sisu_#{vi[:version]}.orig.tar.xz " \ + + "(#{vi[:date]}:#{vi[:date_stamp].gsub(/20\d\dw/,'')})\n" + else line + end + end + if changelog_arr_current.length == changelog_arr_next.length + changelog_file=File.new(fn,'w+') + changelog_arr_next.flatten.each do |line| + changelog_file << line + end + changelog_file.close + else puts "expected changelog arrays to have same length, in: #{changelog_arr_current.length}, out: #{changelog_arr_next.length}" + end + else + puts %{*WARN* is the file or directory writable? could not create #{filename}} + end + end + end + def self.changelog_header_stable_filename + Version_info::Current.changelog_file_stable + end + def self.changelog_header_stable + ch=changelog_header(Version_info::Current.setting_stable) + changelog_header_release( + changelog_header_stable_filename, + ch, + Version_info::Current.setting_stable + ) + end + def self.changelog_header_pre_release(vi) + vn=version_number(vi) + <<-WOK +- sisu_#{vn}.orig.tar.xz (Open commit window: #{vi[:date]}; Pre-Release) + http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/sisu_#{vn} + WOK + end + def self.changelog_header_pre_release_write(filename,ch) + ans=%{update #{Project_details.name.downcase} changelog header, open version: + + #{ch} +proceed? } + resp=Utils.answer?(ans) + if resp + fn="#{Dir.pwd}/#{filename}" + if File.writable?(fn) + changelog_arr_current = IO.readlines(fn) + changelog_arr_next=changelog_arr_current.each.map do |line| + if line =~/^--- HEAD ---$/ + line << ("\n" + ch) + else line + end + end + if changelog_arr_current.length == changelog_arr_next.length + changelog_file=File.new(fn,'w+') + changelog_arr_next.flatten.each do |line| + changelog_file << line + end + changelog_file.close + else puts "expected changelog arrays to have same length, in: #{changelog_arr_current.length}, out: #{changelog_arr_next.length}" + end + else + puts %{*WARN* is the file or directory writable? could not create #{filename}} + end + end + end + def self.changelog_header_stable_pre_release + ch=changelog_header_pre_release(Version_info::Current.setting_stable) + changelog_header_pre_release_write(changelog_header_stable_filename,ch) + end + def self.commit_changelog(rel=:release,msg) + system(%{ + git commit -a -m"#{msg}" + git commit --amend + }) + end + def self.tag_upstream + system(%{ + git tag -af sisu_#{SiSU_version} -m"SiSU #{SiSU_version}" + }) + end + def self.changelog_header_commit(rel=:release) + msg=(rel == :pre_release) \ + ? "version & changelog, open commit window" + : "version & changelog, tag for release" + ans=%{commit #{msg}:\n\nproceed? } + resp=Utils.answer?(ans) + if resp + commit_changelog(rel,msg) + end + end + def self.changelog_header_commit_tag_upstream(rel=:release) + msg=(rel == :pre_release) \ + ? "version & changelog, open commit window" + : "version & changelog, tag for release" + ans=%{commit #{msg}:\n\nproceed? } + resp=Utils.answer?(ans) + if resp + commit_changelog(rel,msg) + tag_upstream + end + end + end + self +end +module GitExtractTaggedVersionBuild + def upstream + system(%{ git checkout upstream }) + end + def self.git_tagged_versions(tag=nil) + if tag + v=if tag =~/sisu_[0-9](?:\.[0-9]){0,2}$/ then tag + elsif tag =~/^[0-9](?:\.[0-9]){0,2}$/ then 'sisu_' + tag + else 'sisu_' + end + system(%{ git tag -l | ag --nocolor '^#{v}' }) + end + end + def self.git_checkout_and_build_and_install_version(tag,options) + begin + ver=if tag =~/sisu_[0-9]\.[0-9]+\.[0-9]+/ then tag + elsif tag =~/^[0-9]\.[0-9]+\.[0-9]+/ then 'sisu_' + tag + else branch + end + create=options[:create] ? '--create ' : '' + build=options[:build] ? '--build ' : '' + install=options[:install] ? '--install ' : '' + commands =<<-WOK + git checkout #{ver} && + #{$called_as} gem #{ver} #{create}#{build}#{install}; + WOK + puts commands + begin + system(commands) + rescue + end + rescue + ensure + system(%{ + git checkout upstream + }) + end + end +end +module Gemspecs + def self.info(vi) + puts <<-WOK +-- +name: #{vi[:project].downcase} +version: #{vi[:version_number]} +date: #{vi[:date]} +summary: #{vi[:project]} + WOK + end + def self.contents(vi) + <<-WOK +Gem::Specification.new do |s| + s.name = '#{vi[:project].downcase}' + s.version = '#{vi[:version_number]}' + s.date = '#{vi[:date]}' + s.summary = '#{Project_details.summary} (linux calls)' + s.description = '#{Project_details.description} [#{Version_info.version_number_info(vi)}] (linux calls & without external dependencies)' + s.homepage = '#{Project_details.homepage}' + s.authors = ["Ralph Amissah"] + s.email = 'ralph.amissah@gmail.com' + s.license = 'GPL-3.0-or-later' + s.files = Dir['lib/#{Project_details.name.downcase}.rb'] + + Dir['lib/#{Project_details.name.downcase}/*.rb'] + + Dir['data/#{Project_details.name.downcase}/version.yml'] + + Dir['data/#{Project_details.name.downcase}/image/*'] + + Dir['bin/#{Project_details.name.downcase}gem'] + + Dir['bin/#{Project_details.name.downcase}'] + s.executables << '#{Project_details.name.downcase}gem' << '#{Project_details.name.downcase}' + s.has_rdoc = false +end + WOK + end + def self.contents_git(vi) + <<-WOK +Gem::Specification.new do |s| + s.name = '#{vi[:project].downcase}' + s.version = '#{Version_info.version_number_use(vi)}' + s.date = '#{vi[:date]}' + s.summary = '#{Project_details.summary} (linux calls)' + s.description = '#{Project_details.description} [#{Version_info.version_number_info(vi)}] (linux calls & without external dependencies)' + s.homepage = '#{Project_details.homepage}' + s.authors = ["Ralph Amissah"] + s.email = 'ralph.amissah@gmail.com' + s.license = 'GPL-3.0-or-later' + s.files = `git ls-files -z lib`.split("\x0") + + Dir['data/#{Project_details.name.downcase}/version.yml'] + + Dir['data/#{Project_details.name.downcase}/image/*'] + + Dir['bin/#{Project_details.name.downcase}gem'] + + Dir['bin/#{Project_details.name.downcase}'] + s.executables << '#{Project_details.name.downcase}gem' << '#{Project_details.name.downcase}' + s.has_rdoc = false +end + WOK + end + def self.create(filename,gemspec) + fn="#{Dir.pwd}/#{filename}.gemspec" + if File.writable?("#{Dir.pwd}/.") + file_sisu_gemspec=File.new(fn,'w+') + file_sisu_gemspec << gemspec + file_sisu_gemspec.close + else + puts %{*WARN* is the file or directory writable? could not create #{filename}} + end + end + def self.build(fn) + system(%{ gem build #{fn}.gemspec }) + end + def self.install(vn) + system(%{ + sudo gem install --local --no-document --verbose sisu-#{vn}.gem + }) + end + module Current + def self.filename + Project_details.name.downcase + end + def self.filename_stable + Project_details.name.downcase \ + + '-' \ + + Version_info::Current.setting_stable[:version_number] + end + def self.info_stable + Gemspecs.info(Version_info::Current.setting_stable) + end + def self.current_stable + Gemspecs.contents( + Version_info::Current.setting_stable, + ) + end + def self.current_git_version + Gemspecs.contents_git( + Version_info::Current.setting_stable, + ) + end + def self.create_stable(version=:version_standard) + (version==:version_git) \ + ? (Gemspecs.create(filename,current_git_version)) + : (Gemspecs.create(filename,current_stable)) + end + def self.build_stable + Gemspecs.build(filename) + end + def self.install_stable(version=:version_standard) + vi=Version_info::Current.setting_stable + vn=((version==:version_git) \ + && (Version_info.version_number_use(vi) != vi[:version_number])) \ + ? (Version_info.version_number_use(vi)) + : (vi[:version_number]) + Gemspecs.install(vn) + end + end +end +module Package + def self.sequence + puts <<-WOK + --open-version # update package version + --version-and-tag-for-release # git tags upstream version + # not included: + # --merge # git merge upstream tag into debian/sid + # --dch # dch create and edit + # --dch-commit # dch commit + # --build # git-buildpackage + # --git_push # git push changes + # --dput # dput package + # --reprepro_update # reprepro update + # --reprepro_push # reprepro rsync changes + WOK + end +end +__END__ +#+END_SRC + +* sisu thor lib + +#+BEGIN_SRC ruby :tangle ../lib/sisu/sisu_thor_lib.rb +# <<sisu_document_header>> +module SiSU_Po4a_Actions + require_relative 'utils_response' # utils_response.rb + include SiSU_Response + @@source=@@targets=nil + def project_details + def name + 'SiSU translations under po4a management' + end + def name_warning + <<-WOK +#{name} + +WARNING all sisu markup files (.ssm, .sst, .ssi) in languages other than #{language.source_language_selected} +are managed by po4a, through translations of the source language to other languages. + +#{language.info_on_selection} + WOK + end + def setup_project + "Setup file for placing #{name}" + end + self + end + def notice + def warn_and_proceed? + '*WARNING* this software module creates, destroys, overwrites directories' + "\n" \ + + '*WARNING*: Use this Software at your own risk!' + end + def default(selection=nil) + selections=:strict #selections=:short + ans=if selection + case selection + when selection.is_a?(String) + selections=:strict + <<-WOK + #{project_details.setup_project} + Default action selected - "#{selection} #{project_details.name}" +#{warn_and_proceed?} + WOK + when :make + selections=:strict + <<-WOK + #{project_details.setup_project} + "--#{selection}" selected - #{selection} #{project_details.name} + selected (or configured) languages to be used + source language: #{language.source_language_available_str} + target languages: #{language.translation_languages_selected_that_are_available.inspect} + + WARNING: this action assumes (and places) this project is under po4a + (translation) management. It will create sub-directories for the + selected (or configured) target languages: + #{language.translation_languages_selected_that_are_available.inspect} + & the po4a configuration file: #{filename.po4a_cfg} + in the current directory: + #{Dir.pwd} + It will populate the sub-directories with translation files created from + the pot and po files found under the corresponding language + sub-directories, (under #{dir.pot}/ & #{dir.po}/). + (OVERWRITING any existing translated .ssm .sst .ssi files + in language subdirectories that are not under po4a management). + + You should backup the current directory: + #{Dir.pwd} + +#{warn_and_proceed?} + WOK + when :clean + selections=:strict + <<-WOK + #{project_details.setup_project} + "--#{selection}" selected - #{selection} #{project_details.name} +#{warn_and_proceed?} + WOK + when :distclean + selections=:strict + <<-WOK + #{project_details.setup_project} + "--#{selection}" selected - #{selection} #{project_details.name} + WARNING: this action assumes (and places) this project is under po4a + (translation) management. It will remove the sub-directories (if they exist): + #{language.possible_translations.inspect} + + #{language.translation_languages_selected_that_are_available.inspect} + & file: #{filename.po4a_cfg} + in the current directory: + #{Dir.pwd} + Note: these sub-directories & the config file #{filename.po4a_cfg} + should be auto-generated from pot and po files if this project translation + is under po4a management. + This query is to give you the chance to make sure you know what you are doing. +#{warn_and_proceed?} + WOK + when :rebuild + selections=:strict + <<-WOK + #{project_details.setup_project} + "--#{selection}" selected - #{selection} #{project_details.name} + WARNING: this action assumes (and places) this project is under po4a + (translation) management. It will destroy/clobber and then create again the + sub-directories: + #{language.translation_languages_selected_that_are_available.inspect} + populating them with translation files created from the pot and po files + found under the corresponding language sub-directories in (#{dir.pot}/ + & #{dir.po}/). + It will also generate the file: #{filename.po4a_cfg} + These actions will be taken in the current directory: + #{Dir.pwd} + This query is to give you the chance to make sure you know what you are doing. +#{warn_and_proceed?} + WOK + else + selections=:strict + <<-WOK + #{project_details.setup_project} + Default action selected - "#{selection} #{project_details.name}" +#{warn_and_proceed?} + WOK + end + else + selections=:strict + <<-WOK + #{project_details.setup_project} + Default action selected - "install and to setup #{project_details.name}" +#{warn_and_proceed?} + WOK + end + exit unless query.answer?(ans) + end + def project_help + puts <<-WOK +#{project_details.name} +#{project_details.setup_project} + +This setup file is primarily to assist with having sisu markup files under po4a +translation management. It assumes that the source language files are placed +under the sub-directory identifying the source language set, which is currently +#{language.source_language_selected} +The files there are used to make the source translation file in the directory #{dir.pot}/ +Which is then used to create files for translation under the directory #{dir.po}/ +in sub-directories bearing the translation languages ISO code. + +The current language translation selection is: #{translation_languages_selected_str} +The languages selected are located in the file: #{filename.languages_src_tgt} + +sisu available language list: #{sisu_languages_available_str} + + WOK + end + self + end + def generate + def readme + system(%{ruby ../../../../../bin/sisu6 --txt -v --no-manifest --dump='../../../../../..' en/README.ssm}) + end + def manpage + system(%{ruby ../../../../../bin/sisu6 --manpage -v --no-manifest --dump='../../../../../../man/man1' en/sisu.ssm}) + end + self + end + def filename + def languages_src_tgt + #'translation_languages' + 'languages_source_and_targets' + end + def po4a_cfg + 'po4a.cfg' + end + self + end + def dir + def pwd + Dir.pwd + end + def po4a_ + 'po4a/' # '' + end + def pot + po4a_ + 'pot' + end + def po + po4a_ + 'po' + end + self + end + def dir_mk(dir) + FileUtils::mkdir_p(dir) unless FileTest.directory?(dir) + end + def po4a_flags + def debug + '-d -v' + end + def normal + '' + end + def quiet + '-q' + end + self + end + def languages_from_file + def language_source + if @@source.is_a?(String) \ + and @@source =~ /w{2,4}/ + else languages_extract_from_file + end + @@source + end + def language_targets + if @@targets.is_a?(Array) \ + and @@targets.length > 0 + else languages_extract_from_file + end + @@targets + end + def languages_extract_from_file + if (@@source.is_a?(String) \ + and @@source =~/\w{2,4}/) \ + and (@@targets.is_a?(Array) \ + and @@targets.length > 0) + else + if FileTest.file?(filename.languages_src_tgt) + puts 'file: "' + filename.languages_src_tgt + '" found and used (unless overridden)' + langs=IO.read(filename.languages_src_tgt, mode: 'r:utf-8').scan(/source:\s+\w+|target:\s+\w.+/) + langs.each do |sel| + case sel + when /source:/ + source=sel.split(/source:\s*|\s+/).join + source=(source =~/\w{2,4}/) ? source : nil + @@source=unless @@source.is_a?(String) \ + and @@source =~/\w{2,4}/ + source + else @@source + end + when /target:/ + @@targets=unless @@targets.is_a?(Array) + sel.split(/targets?:\s*|\s+/) - [''] + else @@targets + end + end + end + else + puts %{(create) missing instruction file: "#{filename.languages_src_tgt}"\n contents e.g.:\n source: en\n target: de fr es ja ru zh\n no po target languages found} + exit + end + end + end + self + end + def language + def source_language_selected(src=nil) + @@source=if not @@source.nil? \ + and @@source.is_a?(String) \ + and @@source =~/\w{2,4}/ + @@source + elsif (src \ + && src.is_a?(String) \ + && src.length > 1) + src + else + src=languages_from_file.language_source + end + end + def translation_languages_selected(targets=nil) #translation_languages + @@targets=if not @@targets.nil? \ + and @@targets.is_a?(Array) \ + and @@targets.length > 0 + @@targets + elsif (targets \ + && targets.is_a?(Array) \ + && targets.length > 0) + targets + else + targets=languages_from_file.language_targets + end + end + def source_language_available + [source_language_selected] & sisu_languages_available + end + def translation_languages_selected_that_are_available + translation_languages_selected & sisu_languages_available + end + def info_on_selection + if translation_languages_selected != translation_languages_selected_that_are_available + <<-WOK +WARNING: language selections mismatch + +The current language translation selection appears to be: #{translation_languages_selected_str} +Of which the following are valid (available) selections: #{translation_languages_selected_that_are_available_str} + +sisu available language list: #{sisu_languages_available_str} + +the following will be used: #{translation_languages_selected_that_are_available_str} +The languages selected are located in the file: #{filename.languages_src_tgt} + WOK + else + <<-WOK +The current language translation selection is: #{translation_languages_selected_str} +The languages selected are located in the file: #{filename.languages_src_tgt} + +sisu available language list: #{sisu_languages_available_str} + WOK + end + end + def sisu_languages_available + $SiSU_Language_Codes.language_list.codes + end + def possible_translations + sisu_languages_available - [source_language_selected] + end + def translation_languages_selected_str + language.translation_languages_selected.join(' ') + end + def source_language_available_str + source_language_available.join + end + def translation_languages_selected_that_are_available_str + language.translation_languages_selected_that_are_available.join(' ') + end + def sisu_languages_available_str + language.sisu_languages_available.join(' ') + end + def posible_translations_str + language.posible_translations.join(' ') + end + self + end + def files_src + def ssm + Dir.glob("#{language.source_language_selected}/*.ssm").sort + end + def sst + Dir.glob("#{language.source_language_selected}/*.sst").sort + end + def ssi + Dir.glob("#{language.source_language_selected}/*.ssi").sort + end + def all + Dir.glob("#{language.source_language_selected}/*{.ssm,.sst,.ssi}").sort + end + self + end + def po4a_cfg_file + File.open("#{Dir.pwd}/#{filename.po4a_cfg}",'w') + end + def po4a_create + def configure #po4a_cfg + po4a_cfg_arr=[] + po4a_cfg_arr \ + << "[po4a_langs] #{language.translation_languages_selected_that_are_available_str}" + po4a_cfg_arr \ + << "[po4a_paths] #{dir.pot}/$master.pot $lang:#{dir.po}/$lang/$master.po" + files_src.ssm.each do |file_src| + file_src_fn=file_src.gsub(/#{language.source_language_selected}\//,'') + po4a_cfg_arr \ + << "[type: text] #{file_src} $lang:$lang/#{file_src_fn}" + end + files_src.sst.each do |file_src| + file_src_fn=file_src.gsub(/#{language.source_language_selected}\//,'') + po4a_cfg_arr \ + << "[type: text] #{file_src} $lang:$lang/#{file_src_fn}" + end + files_src.ssi.each do |file_src| + file_src_fn=file_src.gsub(/#{language.source_language_selected}\//,'') + po4a_cfg_arr \ + << "[type: text] #{file_src} $lang:$lang/#{file_src_fn}" + end + file=po4a_cfg_file + po4a_cfg_arr.each do |txt| + puts txt + file << txt << "\n" + end + file.close + cmd='po4a --keep 0 ' \ + + po4a_flags.normal + ' ' \ + + filename.po4a_cfg + #cmd='po4a --keep 0 --no-backups --package-name ' \ + ,#+ 'sisu-manual' + ' ' \ + ,#+ po4a_flags.normal + ' ' \ + ,#+ filename.po4a_cfg + system(cmd); puts cmd + end + self + end + def project + def make + dir_mk(dir.pot) + language.translation_languages_selected_that_are_available.each do |lang_dir| + dir_lang="#{Dir.pwd}/#{dir.po}/#{lang_dir}" + dir_mk(dir_lang) + end + po4a_create.configure + end + def clean + #rm -f po/*/*.po~ + #rm -rf ../build + FileUtils.rm_f Dir.glob("./#{dir.po}/*/*.po~") + end + def distclean + #rm -f po4a.cfg + #rm -rf $(LANGUAGES) + FileUtils::rm_f(filename.po4a_cfg) + FileUtils::rm_r(language.possible_translations,:force => true) + end + self + end +end +__END__ +#+END_SRC + +* Rake & Rant +** Rake & Rant + +#+BEGIN_SRC ruby :tangle ../setup/rbuild :tangle-mode (identity #o755) :shebang #!/usr/bin/env ruby +=begin + Common Rakefile, Rantfile installer for SiSU + softlink Rakefile and Rantfile to this file + + - Homepage: <http://search.sisudoc.org> + - Download: <http://www.jus.uio.no/sisu/download> + + Copyright (C) 2007 Ralph Amissah + + - License: LGPL - GNU Lesser General Public License + [same license as Rant provided within the Rant package] + + - Ralph Amissah <ralph.amissah@gmail.com> + + Rake is a Ruby build program by Jim Weirich + - Rake may be downloaded and installed from: + <http://rake.rubyforge.org/> + + Rant is a Ruby build program by Stefan Lang + - Rant may be downloaded and installed from: + <http://make.rubyforge.org/> + + Notes on use: + [if rake is preferred and installed] + rake -T + [if rant is preferred and installed] + rant -T + + SiSU can also be Setup/Installation using: + * Minero Aoki's setup.rb, provided along with SiSU, or + +=end +#%% produce a makefile suitable for the target platform +#require 'mkmf' +#create_makefile("sisu") +#% manual settings, edit/update as required (note current default settings are obtained from sisu version yml file) +require 'find' +require 'fileutils' +#require 'ftools' +require 'rbconfig.rb' +require 'yaml' +include FileUtils +require_relative 'sisu_version' # sisu_version.rb + include SiSUversion +require_relative 'rbuild_libs' # rbuild_libs.rb + include Project_details + include Utils + include Version_info + include Gemspecs + include GitExtractTaggedVersionBuild +require_relative 'rbuild_help' # rbuild_help.rb + include Help +#% tasks +desc "show rake/rant tasks for sisu install, and sisu gem (create spec, build &) install" +task :default => + [:note_sources,:tasks,:note_installation] #[:default_notice,:setup_base] +desc "Setup/Install #{Project_details.name}" +task :setup_project=> + [:setup_bin_,:setup_lib_,:setup_conf_,:setup_share_,:setup_data_,:setup_man_,:setup_vim_,:src_note] +task :project=> \ + [:setup_project] +desc "Setup/Install #{Project_details.name}" +task :setup=> + [:setup_bin_, :setup_lib_,:setup_conf_,:setup_share_,:setup_data_] #, :help] +desc "Setup/Install #{Project_details.name}: bin, lib and conf (no data)" +task :setup_base=> + [:setup_bin_,:setup_lib_,:setup_conf_,:setup_share_,:setup_man_,:setup_vim_,:note_sources] +task :base=> + [:setup_base] +desc "Setup/Install #{Project_details.name}: bin, lib, conf & data" +task :setup_with_data=> + [:setup_base,:setup_data] +desc "check package version" +task :sisuversion => + [:sisu_version] +task :version => + [:sisu_version] +#desc "set package version" +task :sisuversionset => + [:sisu_version_set,:changelog_headers] +desc "check gemspec info" +task :gem_spec => + [:gemspec_info] +desc "create sisu v_stable gemspec" +task :gem_create_spec_stable => + [:gemspecs_stable_create_default_version] +task :gem5cs => + [:gem_create_spec_stable] +task :gem5createspecs => + [:gemspecs_stable_create_default_version] +desc "create gemspec" +task :gem_create_spec => + [:gemspecs_create_default_version] +task :gem_create => + [:gemspecs_create_default_version] +task :gemc => + [:gemspecs_create_default_version] +#--- +desc "build gem" +task :gem_build => + [:gem_build_] +task :gemb => + [:gem_build] +task :gembuild => + [:gem_build] +desc "build sisu v_stable gem" +task :gem_build_stable => + [:gem_stable_build] +task :gem5b => + [:gem_build_stable] +task :gem5build => + [:gem_build_stable] +#--- +desc "create, build & install sisu v_stable gem" + task :gem_create_build_install_stable => + [:gemspecs_stable_create_default_version,:gem_stable_build,:gem_stable_install] +task :gem5cbi => + [:gem_create_build_install_stable] +desc "create, build & install sisu gem" +task :gem_create_build_install => + [:gemspecs_create_default_version,:gem_build_,:gem_install_] +task :gemcbi => + [:gem_create_build_install] +#--- +desc "install gem" +task :gem_install => + [:gem_install_] +task :gemi => + [:gem_install] +task :geminstall => + [:gem_install] +desc "build & install sisu v_stable gem" +task :gem_build_install_stable => + [:gem_stable_build,:gem_install_] +task :gem5bi => + [:gem_build_install_stable] +desc "build & install gem" +task :gem_build_install => + [:gem_build,:gem_install_] +task :gembi => + [:gem_build_install] +#-- manually set next version +#desc "create sisu v_stable gemspec, manually set next version" +task :gem5csn => + [:gemspecs_stable_create_next_version] +#desc "create gemspec, manually set next version" +task :gemcsn => + [:gemspecs_create_next_version] +task :gemcn => + [:gemspecs_create_next_version] +#desc "build gem, manually set next version" +task :gembn => + [:gem_build_next_version] +#desc "build sisu v_stable gem, manually set next version" +task :gem5bn => + [:gem_stable_build_next_version] +#desc "install gem, manually set next version" +task :gemin => + [:gem_install_next_version] +#desc "build & install sisu v_stable gem, manually set next version" +task :gem5bin => + [:gem_stable_build_next_version,:gem_install_next_version] +#desc "build & install gem, manually set next version" +task :gembin => + [:gem_build_next_version,:gem_install_next_version] +#desc "create, build & install sisu v_stable gem, manually set next version" +task :gem5cbin => + [:gemspecs_stable_create_next_version,:gem_stable_build_next_version,:gem_stable_install_next_version] +#desc "create, build & install sisu gem, manually set next version" +task :gemcbin => + [:gemspecs_create_next_version,:gem_build_next_version,:gem_install_next_version] +#--- +#desc "check changelog headers" +task :changelogheaders => + [:changelog_headers] +task :dev => + [:note_developer] +task :developer_note => + [:note_developer] +if File.directory?('bin') + desc "Setup #{Project_details.name} bin only, synonym :bin" + task :setup_bin => + [:setup_bin_] + task :bin => + [:setup_bin] +end +if File.directory?('lib') + desc "Setup #{Project_details.name} lib only, synonym :lib" + task :setup_lib => + [:setup_lib_] + task :lib => + [:setup_lib] +end +if File.directory?('conf') + desc "Setup #{Project_details.name} conf only, synonyms :conf & :etc" + task :setup_conf => + [:setup_conf_] + task :conf => + [:setup_conf] + task :setup_etc => + [:setup_conf] + task :etc => + [:setup_conf] +end +if File.directory?('data') + desc "Setup #{Project_details.name} data only, synonyms :data & :examples" + task :setup_data => + [:setup_data_] + task :data => + [:setup_data] + task :setup_examples => + [:setup_data] + task :examples => + [:setup_data] +end +if File.directory?('data/sisu') + #desc "Setup #{Project_details.name} shared data only (odf & shared images)" + task :setup_share => + [:setup_share_] + task :share => + [:setup_share] +end +if File.directory?('man') + desc "Setup #{Project_details.name} man pages only, synonyms :man" + task :setup_man => + [:setup_man_] + task :man => + [:setup_man] +end +if File.directory?('data/vim') + desc "Setup #{Project_details.name} vim config files only, synonyms :vim" + task :setup_vim => + [:setup_vim_] + task :vim => + [:setup_vim] +end +desc "Remove #{Project_details.name} (all versions)" +task :remove_package => + [:remove_bin, :remove_lib, :remove_conf] +if File.directory?('bin') + #desc "Remove #{Project_details.name} bin only" + task :remove_bin => + [:remove_bin] +end +if File.directory?('lib') + #desc "Remove #{Project_details.name} lib only" + task :remove_lib => + [:remove_lib] +end +if File.directory?('conf') + #desc "Remove #{Project_details.name} conf only" + task :remove_conf => + [:remove_conf] +end +desc "Re-setup #{Project_details.name}, synonym :reinstall" +task :resetup => + [:remove, :setup] +task :reinstall => + [:remove, :setup] +#desc "Re-setup #{Project_details.name}: bin, lib, conf (ignore data), synonym :reinstall" +task :resetup_base => + [:remove, :setup_base_] +task :reinstall_base => + [:remove, :setup_base_] +if File.directory?('bin') + #desc "Re-setup #{Project_details.name} bin, synonym :reinstall" + task :resetup_bin => + [:remove_bin, :setup_bin_] + task :reinstall_bin => + [:remove_bin, :setup_bin_] +end +if File.directory?('lib') + #desc "Re-setup #{Project_details.name} lib, synonym :reinstall_lib" + task :resetup_lib => + [:remove_lib, :setup_lib_] + task :reinstall_lib => + [:remove_lib, :setup_lib_] +end +if File.directory?('conf') + #desc "Re-setup #{Project_details.name} conf, synonyms :reinstall_conf & :resetup_etc" + task :resetup_conf => + [:remove_conf, :setup_conf_] + task :reinstall_conf => + [:remove_conf, :setup_conf_] + task :resetup_etc => + [:remove_conf, :setup_conf_] + task :reinstall_etc => + [:remove_conf, :setup_conf_] +end +if File.directory?('data/sisu') + #desc "Re-setup #{Project_details.name} shared data, (odf & images)" + task :resetup_share => + [:remove_share, :setup_share_] + task :reinstall_share => + [:remove_share, :setup_share_] +end +if File.directory?('man') + #desc "Re-setup #{Project_details.name} man, synonym :reinstall_man" + task :resetup_man => + [:remove_man, :setup_man_] + task :reinstall_man => + [:remove_man, :setup_man_] +end +desc 'Setup Note' +task :setup_note => + [:help] +desc "System information used by #{Project_details.name}" +task :system => + [:system_info,:project_help,:note_sources] +desc "show all system info available - parameters found" +task :system_param => + [:system_param_] +desc "Gem environment information used ruby gems for #{Project_details.name}" +task :gem_env => + [:gem_env_] +desc 'Help' +task :help => + [:project_help,:system_info,:tasks] +#desc "Setup/Install #{Project_details.name} (uses filelist)" +task :install => + [:default_notice,:project] +task :install_bin => + [:setup_bin_] +#desc "search for a version tag e.g. 'tag[5.6.0]'" +task :tag, [:tag] do |t, args| + args.with_defaults(:tag => Version_info::Next.setting_stable[:version]) + puts "Check for Version Tag: #{args.tag}" + print "Version Tag: " + GitExtractTaggedVersionBuild::git_tagged_versions(args) +end +#desc "build and install a specific git tagged version of sisu, e.g. 'build[5.6.0]'" +task :build, [:tag, :branch] => :done do |t, args| + args.with_defaults(:tag => '5.6.0', :branch => 'stable') + puts "Version Tag: #{args.tag}" + puts "Branch: #{args.branch}" + GitExtractTaggedVersionBuild::git_tagged_versions(args.tag) + ans= <<-WOK +Gem Install SiSU Version + WOK + resp=Utils.answer?(ans) + exit unless resp + GitExtractTaggedVersionBuild::git_checkout_and_build_version(args) +end +task :done do + puts 'done' +end + #%% setup/install tasks +task :rant_independence do #notice + resp='' + while resp.length < 4 + resp='sisu-install' #default name install + print %{#{Project_details.rake_rant} + Create a rant dependency independent file + provide filename default name is "install" + [Warning, will overwrite file of name provided + provide name or "quit" to exit]: } + exit if resp =~/^(?:n|quit|exit)$/ + end + remove='y' #remove='n' + if remove =~/y/ + system("rant-import --force --auto #{resp}; + chmod 755 #{resp} + ") + else #puts "#{resp} not replaced" + end +end + +task :default_notice do #notice + Utils.default_notice +end +task :default2 do #secondary + setup_find_cp_r('bin',Project_details.dir.bin) \ + if File.directory?('bin') + setup_find_cp_r('lib',Project_details.dir.lib) \ + if File.directory?('lib') + setup_find_cp_r('conf',Project_details.dir.conf) \ + if File.directory?('conf') + setup_find_cp_r('data/sisu',Project_details.dir.share) \ + if File.directory?('data/sisu') # + setup_find_cp_r('data',Project_details.dir.data) \ + if File.directory?('data') + setup_find_cp_r('data/vim',"#{Project_details.dir.data}/vim") \ + if File.directory?('data/vim') + setup_find_cp_r('man',Project_details.dir.man) \ + if File.directory?('man') +end +task :setup_bin_ do + exclude_files=['sisugem'] + Install.setup_find_create('bin',Project_details.dir.bin,exclude_files) \ + if File.directory?('bin') +end +task :setup_lib_ do + Install.setup_find_create('lib',Project_details.dir.lib) \ + if File.directory?('lib') +end +task :setup_conf_ do + Install.setup_find_create('conf',Project_details.dir.conf) \ + if File.directory?('conf') +end +task :setup_share_ do + Install.setup_find_create('data/sisu',Project_details.dir.share) \ + if File.directory?('data/sisu') +end +task :setup_data_ do + Install.setup_find_create('data',Project_details.dir.data) \ + if File.directory?('data') +end +task :setup_man_ do + Install.setup_find_create('man',Project_details.dir.man) \ + if File.directory?('man') + Install.setup_find_create('man.deb/man',Project_details.dir.man) \ + if File.directory?('man.deb/man') +end +task :setup_vim_ do + Install.setup_find_create('data/vim',Project_details.dir.vim) \ + if File.directory?('data/vim') +end +task :gemspec_info do + Gemspecs.info_stable +end +task :gemspecs_stable_create_default_version do + Gemspecs::Current.create_stable +end +task :gemspecs_create_default_version do + Gemspecs::Current.create_stable +end +task :gemspecs_stable_create_next_version do + Gemspecs::Next.create_stable +end +task :gemspecs_create_next_version do + Gemspecs::Next.create_stable +end +task :gem_stable_build do + Gemspecs::Current.build_stable +end +task :gem_build_ do + Gemspecs::Current.build_stable +end +task :gem_stable_build_next_version do + Gemspecs::Next.build_stable +end +task :gem_build_next_version do + Gemspecs::Next.build_stable +end +task :gem_stable_install do + Gemspecs::Current.install_stable +end +task :gem_install_ do + Gemspecs::Current.install_stable +end +task :gem_stable_install_next_version do + Gemspecs::Next.install_stable +end +task :gem_install_next_version do + Gemspecs::Next.install_stable +end +task :changelog_headers do + puts '---' + puts Version_info::Update.changelog_header_stable +end +task :sisu_version do + puts Version_info::Next.setting_stable + puts '---' + puts Version_info::Current.setting_stable[:project] + puts Version_info::Current.setting_stable[:version] + puts Version_info::Current.setting_stable[:date] + puts Version_info::Current.setting_stable[:date_stamp] +end +task :sisu_version_set do + Version_info::Update.update_stable +end + #%% post install + #%% clobber/remove tasks +task :remove_bin do + rm_r "#{Project_details.dir.bin}/#{Project_details.dir.proj}" \ + if FileTest.file?("#{Project_details.dir.bin}/#{Project_details.dir.proj}") +end +task :remove_lib do + rm_r "#{Project_details.dir.lib}/#{Project_details.dir.proj}" \ + if FileTest.directory?("#{Project_details.dir.lib}/#{Project_details.dir.proj}") +end +task :remove_conf do + rm_r "#{Project_details.dir.conf}/#{Project_details.dir.proj}" \ + if FileTest.directory?("#{Project_details.dir.conf}/#{Project_details.dir.proj}") +end +task :remove_man do + rm_r "#{Project_details.dir.man}/**/#{Project_details.dir.proj}" \ + if FileTest.directory?("#{Project_details.dir.man}/man1/#{Project_details.dir.proj}") +end +task :remove_version do + rm_r "#{Project_details.dir.bin}/#{Project_details.dir.proj}" \ + if FileTest.file?("#{Project_details.dir.bin}/#{Project_details.dir.proj}") + rm_r "#{Project_details.dir.lib}/#{Project_details.dir.proj}/#{Project_details.version}" \ + if FileTest.directory?("#{Project_details.dir.lib}/#{Project_details.dir.proj}/#{Project_details.version}") + rm_r "#{Project_details.dir.conf}/#{Project_details.dir.proj} \ + if FileTest.directory?("#{Project_details.dir.conf}/#{Project_details.dir.proj}") +end +task :remove_package do + rm_r "#{Project_details.dir.bin}/#{Project_details.dir.proj}" \ + if FileTest.file?("#{Project_details.dir.bin}/#{Project_details.dir.proj}") + rm_r "#{Project_details.dir.lib}/#{Project_details.dir.proj}" \ + if FileTest.directory?("#{Project_details.dir.lib}/#{Project_details.dir.proj}") + rm_r "#{Project_details.dir.conf}/#{Project_details.dir.proj}" \ + if FileTest.directory?("#{Project_details.dir.conf}/#{Project_details.dir.proj}") +end +task :note_sources do + puts <<-WOK + + SiSU project: + <http://sisudoc.org> + <http://www.jus.uio.no/sisu> + sisu source code is available at: + <http://git.sisudoc.org> + <http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary> + sisu markup samples are provided/packaged separately as sisu-markup-samples: + <http://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary> + WOK +end +task :note_installation do + puts <<-WOK + alternative 0: distribution install, rather than this Rakefile + a distribution install pulls in the many dependencies used by sisu after + initial processing to generate and store output, significant amongst these are + XeTeX & databases (sqlite3 and postgresql) + + alternative 1: gem install, you need to: + create the gemspec; build the gem (from the gemspec); install the gem + which can be done with the single command: + rake gem_create_build_install # (to build and install sisu v5 & sisu v6, alias gemcbi) + separate gems are made/installed for sisu v5 & sisu v6 contained in source: + rake gem_create_build_install_stable # (to build and install sisu v5, alias gem5cbi) + for individual steps (create, build, install) see rake options, rake -T + to specify sisu version for sisu installed via gem + sisu _#{Version_info::Current.setting_stable[:version]}_ --version + to uninstall sisu installed via gem + sudo gem uninstall --verbose sisu + WOK +end +task :note_developer do + puts <<-WOK + + changelogheaders + + sisuversion + sisuversionset + + gemcsn gem5csn gem6csn + gembn gem5bn gem6bn + gemin gem5in gem6in + gembin gem5bin gem6bin + gemcbin gem5cbin gem6cbin + WOK +end + #%% help & system info +task :system_info do + Project_details.system_info +end +task :system_param_ do + Project_details.env.each {|c| puts c.inspect } +end +task :gem_env_ do + Project_details.gem_env +end +task :project_help do + Help.project_help +end +task :tasks do + Help.tasks +end +#+END_SRC + +** Rake & Rant libs + +#+BEGIN_SRC ruby :tangle ../setup/rbuild_libs.rb +module Project_details + require_relative 'sisu_version' + include SiSUversion + def self.name + 'SiSU' + end + def self.thor + "ruby-thor files for the installation/setup of #{name}" + end + def self.platform_notice + "[#{name} is for Linux/Unix Platforms]" + end + def self.env + RbConfig::CONFIG + end + def self.host + env['host'] + end + def self.dir + def self.proj + Project_details.name.downcase + end + def self.arch + env['archdir'] + end + def self.sitearch + env['sitearchdir'] + end + def self.bin + env['bindir'] + end + def self.lib + env['sitelibdir'] + end + def self.data + env['datadir'] + end + def self.share + "#{env['datadir']}/sisu" + end + def self.conf + env['sysconfdir'] + end + def self.man + env['mandir'] + end + def self.vim + "#{env['datadir']}/sisu/vim" + end + def self.out + "#{env['localstatedir']}/#{proj}" + end + def self.rubylib + env['LIBRUBYARG_SHARED'] + end + def self.pwd + Dir.pwd #ENV['PWD'] + end + self + end + def self.version + stamp={} + v="#{dir.pwd}/data/sisu/version.yml" + if File.exist?(v) + stamp=YAML::load(File::open(v)) + stamp[:version] + else '' + end + end + def self.system_info + ##{Project_details.platform_notice} + puts <<-WOK + Host + host: #{Project_details.host} + arch: #{Project_details.dir.arch} + sitearch: #{Project_details.dir.sitearch} + Directories for installation + bin: #{Project_details.dir.bin} + lib (site-ruby): #{Project_details.dir.lib}/#{Project_details.dir.proj}/v* + conf [etc]: #{Project_details.dir.conf}/#{Project_details.dir.proj} + data (odf, shared images): #{Project_details.dir.share} + vim (vim syntax, highlighting, ftplugin): #{Project_details.dir.data}/sisu/vim + data (README, version_manifest): #{Project_details.dir.data}/doc/#{Project_details.dir.proj} + man (manual pages): #{Project_details.dir.man} + output: #{Project_details.dir.out} + processing: #{Project_details.dir.out}/processing + www: #{Project_details.dir.out}/www + rubylib: #{Project_details.dir.rubylib} + + WOK + end + def self.gem_env + system("gem env") + end +end +module Utils + def self.answer?(ask) + resp='redo' + print ask + " ['yes', 'no' or 'quit']: " + resp=File.new('/dev/tty').gets.strip #resp=gets.strip + if resp == 'yes' then true + elsif resp == 'no' then false + elsif resp =~/^quit|exit$/ then exit + else puts "[please type: 'yes', 'no' or 'quit']" + answer?(ask) + end + end + def self.default_notice # local help not implemented description incorrect + ans= %{#{Project_details.thor} + Information on alternative actions is available using: + [if ruby-thor is installed:] + "rake help") + Default action selected - "install #{Project_details.name}" proceed? } + resp=answer?(ans) + exit unless resp + end + def self.chmod_file(place) + if place =~/\/bin/; File.chmod(0755,place) + else File.chmod(0644,place) + end + end + def self.chmod_util(place) + if place =~/\/bin/; chmod(0755,place) + else chmod(0644,place) + end + end + def self.system_date + `date "+%Y-%m-%d"`.strip + end + def self.system_date_stamp + `date "+%Yw%W/%u"`.strip + end + def self.program_found?(prog) + found=`which #{prog}` #`whereis #{make}` + (found =~/bin\/#{prog}\b/) ? :true : :false + end +end +module Install + #%% using a directory and its mapping + def self.setup_find_create(dir_get,dir_put,exclude_files=['\*'],act) #primary, + begin + Find.find("#{Project_details.dir.pwd}/#{dir_get}") do |f| + stub=f.scan(/#{Project_details.dir.pwd}\/#{dir_get}\/(\S+)/).join + place="#{dir_put}/#{stub}" + action=case + when File.file?(f) + unless f =~/#{exclude_files.join("|")}/ + cp(f,place) + Utils.chmod_file(place) + "-> #{dir_put}/" + end + when File.directory?(f) + FileUtils.mkpath(place) \ + unless FileTest.directory?(place) + "./#{dir_get}/" + else '?' + end + puts "#{action}#{stub}" + end + rescue + puts "\n\n<< are you root? required for install >>" + end + end + def self.setup_find_cp_r(dir_get,dir_put) #secondary, using recursive copy + begin + Find.find("#{Project_details.dir.pwd}/#{dir_get}") do |f| + stub=f.scan(/#{Project_details.dir.pwd}\/#{dir_get}\/(\S+)/).join + place="#{dir_put}/#{stub}" + case + when File.file?(f) + cp_r(f,place) + Utils.chmod_util(place) + when File.directory?(f) + mkdir(place) \ + unless FileTest.directory?(place) + end + end + rescue + puts "\n\n<< are you root? required for install >>" + end + end +end +module Version_info + def self.contents(vi) + <<-WOK +--- +:project: #{vi[:project]} +:version: #{vi[:version]} +:date_stamp: #{vi[:date_stamp]} +:date: "#{vi[:date]}" + WOK + end + def self.git_version_extract + if FileTest.file?('/usr/bin/git') + x=`git describe --long --tags 2>&1`.strip. + gsub(/^[a-z_-]*([0-9.]+)/,'\1'). + gsub(/([^-]*-g)/,'r\1'). + gsub(/-/,'.') + x=(x=~/^[0-9]+\.[0-9]+\.[0-9]+\.r[0-9]+\.g[0-9a-f]{7}/) \ + ? x + : nil + else nil + end + end + def self.version_number_use(vi) + (git_version_extract.nil?) \ + ? (vi[:version]) + : git_version_extract + end + def self.version_number_info(vi) + (Version_info.version_number_use(vi) != vi[:version_number]) \ + ? (%{#{vi[:version_number]} from git #{Version_info.version_number_use(vi)}}) + : vi[:version_number] + end + def self.version_number_info_stable + vi=Version_info::Current.setting_stable + (Version_info.version_number_use(vi) != vi[:version_number]) \ + ? (%{#{vi[:version_number]} from git #{Version_info.version_number_use(vi)}}) + : vi[:version_number] + end + module Current + def self.yml_file_path + 'data/sisu/version.yml' + end + def self.settings(file) + v="#{Dir.pwd}/#{file}" + if File.exist?(v) + YAML::load(File::open(v)) + else '' + end + end + def self.file_stable + yml_file_path + end + def self.setting_stable + hsh=settings(file_stable) + hsh[:version_number]=/([0-9]+\.[0-9]+\.[0-9]+)/. + match(hsh[:version])[1] + hsh + end + def self.content_stable + Version_info.contents(setting_stable) + end + end + module Next + def self.settings(v) + { + project: "#{Project_details.name}", + version: "#{v}", + date: "#{Utils.system_date}", + date_stamp: "#{Utils.system_date_stamp}", + } + end + def self.setting_stable + settings(SiSU_version) + end + def self.content_stable + Version_info.contents(setting_stable) + end + end + module Update + def self.version_info_update_commit(filename,vi_hash_current,vi_content_current,vi_hash_next,vi_content_next) + ans=%{update #{Project_details.name.downcase} version info replacing: + #{vi_hash_current.sort} +with: + #{vi_hash_next.sort} + +#{vi_content_current} becoming: +#{vi_content_next} +proceed? } + resp=Utils.answer?(ans) + if resp + fn="#{Dir.pwd}/#{filename}" + if File.writable?("#{Dir.pwd}/.") + file_version=File.new(fn,'w+') + file_version << vi_content_next + file_version.close + else + puts %{*WARN* is the file or directory writable? could not create #{filename}} + end + end + end + def self.update_stable + version_info_update_commit( + Version_info::Current.file_stable, + Version_info::Current.setting_stable, + Version_info::Current.content_stable, + Version_info::Next.setting_stable, + Version_info::Next.content_stable + ) + end + def self.changelog_header(vi) + <<-WOK +-- #{vi[:version]}.orig.tar.xz (#{vi[:date]}:#{vi[:date_stamp].gsub(/20\d\dw/,'')}) +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/sisu_#{vi[:version]} +http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/debian/sisu_#{vi[:version]}-1 +http://www.jus.uio.no/sisu/pkg/src/sisu_#{vi[:version]}.orig.tar.xz + sisu_#{vi[:version]}.orig.tar.xz + sisu_#{vi[:version]}-1.dsc + WOK + end + def self.changelog_header_stable + changelog_header(Version_info::Current.setting_stable) + end + end + self +end +module GitExtractTaggedVersionBuild + def upstream + system(%{ git checkout upstream }) + end + def self.git_tagged_versions(vb=nil) + if vb.tag + v=if vb.tag =~/sisu_[0-9](?:\.[0-9]){0,2}$/ then vb.tag + elsif vb.tag =~/^[0-9](?:\.[0-9]){0,2}$/ then 'sisu_' + vb.tag + else 'sisu_' + end + system(%{ git tag -l | ag --nocolor '^#{v}' }) + end + end + def self.git_checkout_and_build_version(vb) + begin + ver=if vb.tag =~/sisu_[0-9]\.[0-9]+\.[0-9]+/ then vb.tag + elsif vb.tag =~/^[0-9]\.[0-9]+\.[0-9]+/ then 'sisu_' + vb.tag + else vb.branch + end + install_branch='gem_create_build_stable' + commands =<<-WOK + git checkout #{ver} && + rake #{install_branch}; + WOK + puts commands + system(commands) + ensure + system(%{ + git checkout upstream + }) + end + end + def self.git_checkout_and_build_and_install_version(vb) + begin + ver=if vb.tag =~/sisu_[0-9]\.[0-9]+\.[0-9]+/ then vb.tag + elsif vb.tag =~/^[0-9]\.[0-9]+\.[0-9]+/ then 'sisu_' + vb.tag + else vb.branch + end + install_branch='gem_create_build_install_stable' + commands =<<-WOK + git checkout #{ver} && + rake #{install_branch}; + WOK + puts commands + system(commands) + ensure + system(%{ + git checkout upstream + }) + end + end +end +module Gemspecs + def self.info(vi) + puts <<-WOK +-- +name: #{vi[:project].downcase} +version: #{vi[:version_number]} +date: #{vi[:date]} +summary: #{vi[:project]} + WOK + end + def self.contents(vi) + #s.summary = '#{vi[:project]}' + <<-WOK +Gem::Specification.new do |s| + s.name = '#{vi[:project].downcase}' + s.version = '#{vi[:version_number]}' + s.date = '#{vi[:date]}' + s.summary = '#{Version_info.version_number_info(vi)}' + s.description = 'documents - structuring, publishing in multiple formats and search' + s.authors = ["Ralph Amissah"] + s.email = 'ralph.amissah@gmail.com' + s.files = Dir['lib/#{Project_details.name.downcase}/*.rb'] + + Dir['data/#{Project_details.name.downcase}/version.yml'] + + Dir['data/#{Project_details.name.downcase}/image/*'] + + Dir['bin/#{Project_details.name.downcase}gem'] + + Dir['bin/#{Project_details.name.downcase}'] + s.license = 'GPL-3.0-or-later' + s.executables << '#{Project_details.name.downcase}gem' << '#{Project_details.name.downcase}' +end + WOK + end + def self.create(filename,gemspec) + fn="#{Dir.pwd}/#{filename}.gemspec" + if File.writable?("#{Dir.pwd}/.") + file_sisu_gemspec=File.new(fn,'w+') + file_sisu_gemspec << gemspec + file_sisu_gemspec.close + else + puts %{*WARN* is the file or directory writable? could not create #{filename}} + end + end + def self.build(fn) + system(%{ gem build #{fn}.gemspec }) + end + def self.install(fn) + system(%{ + sudo gem install --no-document --verbose #{fn}.gem + }) + end + module Current + def self.filename_stable + Project_details.name.downcase \ + + '-' \ + + Version_info::Current.setting_stable[:version_number] + end + def self.info_stable + Gemspecs.info(Version_info::Current.setting_stable) + end + def self.current_stable + Gemspecs.contents( + Version_info::Current.setting_stable, + ) + end + def self.create_stable + Gemspecs.create(filename_stable,current_stable) + Gemspecs.create( + "#{Project_details.name.downcase}-stable", + current_stable + ) + end + def self.build_stable + Gemspecs.build(filename_stable) + end + def self.install_stable + Gemspecs.install(filename_stable) + end + end + module Next + def self.filename_stable + Project_details.name.downcase \ + + '-' \ + + Version_info::Next.setting_stable[:version_number] + end + def self.setting_stable + Gemspecs.contents( + Version_info::Next.setting_stable, + ) + end + def self.create_stable + Gemspecs.create(filename_stable,setting_stable) + end + def self.build_stable + Gemspecs.build(filename_stable) + end + def self.install_stable + Gemspecs.install(filename_stable) + end + end +end +#+END_SRC + +** Rake & Rant help + +#+BEGIN_SRC ruby :tangle ../setup/rbuild_help.rb +module Help + def self.project_help + puts <<WOK + +#{Project_details.name} + #{Project_details.rake_rant} + #{Project_details.platform_notice} + +Commands quick start list + #{Project_details.name} Rake/Rant Help: (Rakefile or Rantfile) + rake (rake -T or rant -T) # a task list, (generated by Rake or Rant) for more complete and up to date help + + Quick start install and remove project #{Project_details.name}, as root: + rake setup # install #{Project_details.name} + rake resetup # reinstall #{Project_details.name} + rake remove_package # clobber/remove #{Project_details.name}, all versions + alternatively to install as a gem: + rake gem_create_build_install # create gemspec; build gem, &; install gem, for #{Project_details.name} + + NOTE: these install options DO NOT setup #{Project_details.name} dependencies for: + LaTeX(XeTeX) pdf output; or + databases (postgresql or sqlite3) for #{Project_details.name} search + should you wish to produce outputs that depend on them + (on Debian for example this is the work of the debian installer) + +WOK + end + def self.tasks(make='rake') + begin + system("#{make} -T") + rescue + puts 'is either rake or rant installed?' + end + end +end +#+END_SRC + +* nix + +** envrc + +#+BEGIN_SRC sh :tangle ../.envrc +if type lorri &>/dev/null; then + echo "direnv: using lorri from PATH ($(type -p lorri))" + eval "$(lorri direnv)" +else + # fall back to using direnv's builtin nix support + # to prevent bootstrapping problems. + use nix + NIX_ENFORCE_PURITY=0 +fi +# source an additional user-specific .envrc in ./.envrc-local +if [ -e .envrc-local ]; then + source .envrc-local +fi +#+END_SRC + +** shell.nix + +*** shell.nix TODO + +#+BEGIN_SRC nix :tangle ../shell.nix +{ pkgs ? import <nixpkgs> {} }: +pkgs.mkShell { + buildInputs = [ + (import ./nix/pkglst/packages.nix { inherit pkgs; }) + ]; +} +#+END_SRC + +#+BEGIN_SRC nix :NO-tangle ../shell.nix +{ pkgs ? import <nixpkgs> {} }: +let +in pkgs.mkShell { + buildInputs = with pkgs; [ + nix + bundler + bundix + <<ruby_version_2_7>> + sqlite + unzip + xz + zip + #texlive-combined-full + ]; +} +#+END_SRC + +*** packages.nix +**** default + +#+BEGIN_SRC nix :tangle ../nix/pkglst/packages.nix +{ pkgs ? import <nixpkgs> {} }: +with pkgs; [ + <<packages_nix>> + <<ruby_current>> + <<packages_project_relevant>> +] +#+END_SRC + +**** ruby 2.7 + +#+BEGIN_SRC nix :tangle ../nix/pkglst/packages_rauby_2_7.nix +{ pkgs ? import <nixpkgs> {} }: +with pkgs; [ + <<packages_nix>> + <<ruby_version_2_7>> + <<packages_project_relevant>> +] +#+END_SRC + +**** ruby 2.6 + +#+BEGIN_SRC nix :tangle ../nix/pkglst/packages_rauby_2_6.nix +{ pkgs ? import <nixpkgs> {} }: +with pkgs; [ + <<packages_nix>> + <<ruby_current>> + <<packages_project_relevant>> +] +#+END_SRC + +*** ruby legacy + +#+NAME: ruby_legacy +#+BEGIN_SRC nix +<<ruby_version_2_6>> +#+END_SRC +*** ruby current + +#+NAME: ruby_current +#+BEGIN_SRC nix +<<ruby_version_2_7>> +#+END_SRC + +*** ruby next + +#+NAME: ruby_next +#+BEGIN_SRC nix +<<ruby_version_2_7>> +#+END_SRC + +*** ruby 2.5 - ruby_version_2_5 + +#+NAME: ruby_version_2_5 +#+BEGIN_SRC nix +ruby_2_5 +rubyPackages_2_5.rake +rubyPackages_2_5.sqlite3 +rubyPackages_2_5.thor +#+END_SRC + +*** ruby 2.6 - ruby_version_2_6 + +#+NAME: ruby_version_2_6 +#+BEGIN_SRC nix +ruby +rubyPackages.rake +rubyPackages.sqlite3 +rubyPackages.thor +#+END_SRC + +*** ruby 2.7 - ruby_version_2_7 + +#+NAME: ruby_version_2_7 +#+BEGIN_SRC nix +ruby_2_7 +rubyPackages_2_7.rake +rubyPackages_2_7.sqlite3 +rubyPackages_2_7.thor +#+END_SRC + +*** nix related packages + +#+NAME: nix_packages +#+BEGIN_SRC nix +nix +bundler +bundix +#+END_SRC + +*** project relevant packages + +#+NAME: packages_project_relevant +#+BEGIN_SRC nix + sqlite + unzip + xz + zip + #texlive-combined-full +#+END_SRC + +* descriptions +** README + +#+BEGIN_SRC md :tangle ../README +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/> + +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 [link: <http://www.sisudoc.org/sisu/en/manifest/viral_spiral.david_bollier.manifest.html>] + document manifest [link: <http://www.sisudoc.org/sisu/en/manifest/viral_spiral.david_bollier.manifest.html>] + html, segmented text [link: <http://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier/viral_spiral.david_bollier.toc.html>] + html, scroll, document in one [link: <http://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier.html>] + epub [link: <http://www.sisudoc.org/sisu/en/epub/viral_spiral.david_bollier.epub>] + pdf, landscape [link: <http://www.sisudoc.org/sisu/en/pdf/viral_spiral.david_bollier.landscape.a4.pdf>] + pdf, portrait [link: <http://www.sisudoc.org/sisu/en/pdf/viral_spiral.david_bollier.landscape.a4.pdf>] + odf: odt, open document text [link: <http://www.sisudoc.org/sisu/en/odt/viral_spiral.david_bollier.odt>] + xhtml scroll [link: <http://www.sisudoc.org/sisu/en/xhtml/viral_spiral.david_bollier.xhtml>] + xml, sax [link: <http://www.sisudoc.org/sisu/en/xml_sax/viral_spiral.david_bollier.sax.xml>] + xml, dom [link: <http://www.sisudoc.org/sisu/en/xml_dom/viral_spiral.david_bollier.dom.xml>] + concordance [link: <http://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier/concordance.html>] + dcc, document content certificate (digests) [link: <http://www.sisudoc.org/sisu/en/digest/viral_spiral.david_bollier.hash_digest.txt>] + markup source text [link: <http://www.sisudoc.org/sisu/en/src/viral_spiral.david_bollier.sst>] + markup source (zipped) pod [link: <http://www.sisudoc.org/sisu/en/src/viral_spiral.david_bollier.sst.zip>] + +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 + + +---------------------------------------- + +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 + +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 + +_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 + #+END_SRC + +** a description + +(emacs:evil mode gifts a "vim" of enticing "alternative" powers! ;) +(vim, my _editor_ of choice also in the emacs environment :) + +*** 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 + + documents - structuring, publishing in multiple formats and search + SiSU is a lightweight markup based, command line oriented, document + structuring, publishing and search, static content tool for document + collections. + . + With minimal preparation of a plain-text (UTF-8) file, using sisu markup syntax + in your text editor of 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 of being able to finely match text in documents, using + common object numbers, across different output formats and across languages if + you have translations of the same document. For search, 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 and the means to make book indexes that make use + of its object numbering. + . + Syntax highlighting and folding (outlining) files are provided for the Vim and + Emacs 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. + +**** 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, + but also some forms of technical writing), that is tasked to address certain + challenges I identified as being of interest to me over the years in open + publishing. + + The idea and implementation may be of interest to consider as some of the + issues encountered and that it seeks to address are known and common to such + endeavors. Amongst them: + + * how do you ensure what you do now can be read in decades? + * how do you keep up with new changing and technologies? + * do you select a canonical format to represent your documents, if so + what? + * how do you reliably cite (locate) material in different document + representations? + * how do you deal with multilingual texts? + * what of search? + * how are documents contributed to the collection? + + (these questions are selected in to help describe the direction of efforts with + regard to sisu). + + My Dabblings in the Domain of Open Publishing + --------------------------------------------- + + The system is called SiSU, it is an offshoot of my early efforts at finding out + what to make of the web, that started at the University of Tromsø in 1993 (an + early law website Ananse/ International Trade Law Project / Lex Mercatoria). I + have worked on SiSU continually since 1997 and it has been open source in 2005 + (under a license called GPL3+), though I remain its developer. + + In working in this field I have had to address some of the common issues. + + So how do you ensure what you do now can be read in decades to come? There are + alternative solutions. (i) stick with a widely used and not overly complicated + well document open standard, and for that the likes of odf is an excellent + choice (ii) alternatively go for the most basic representation of a document + that meets your needs, in my case based on UTF-8 text and some markup tags, + fairly easily parsable by the human eye and as long as utf8 is in use it will + always be possible to extract the information + + How do you keep up with new changing and technologies? Here my solution has + been to generate new versions of the substantive content so as to always have + the latest document representations available e.g. HTML has changed a lot over + the years, different specifications come out for various formats including ODF, + electronic readers have become an important viewing alternative, introducing + the open reader format EPUB. Output representations are generated from source + documents. Different open document file formats can be produced and databases + and search engines populated. (The source documents and interpreter are all + that are required to re-create site content. Source documents can be made + public or retained privately). The strict separation of a simple source + document from the output produced, means that with updates to SiSU (the + interpreter/processor/generator), outputs can be updated technically as + necessary, and new output formats added when needed. Amongst the output formats + currently supported are HTML, LaTeX generated Pdfs (A4, letter, other; + landscape, portrait), Epub, Open Document Format text. Returning to HTML as an + example, it has changed a lot over the years I have worked with it, this way of + working has meant it is possible to keep producing current versions of HTML, + retaining the original substantive document... and new formats have been added + as thought desired. There is no attempt to make output in different document + formats/ representations look alike let alone identical. Rather the attempt is + to optimize output for the particular document filetype, (there is no reason + why an epub document would look or behave like an open document text or that a + Pdf would look like HTML output; rather PDF is optimized for paper viewing, + HTML for screen etc.) Wherever possible features associated with the + particular output type are taken advantage of. This freedom is made possible to + a large extent by the answer to the question that follows. + + How do you reliably cite (locate) material in different document + representations? The traditional answer has been to have a canonical + publication, and resulting fixed page numbers. This was not a viable solution + for HTML (which changes from one viewer to another and with selectable font + faces & size etc.); nor is it otherwise ideal in an electronic age with the + possibility of presenting/interacting with material/documents in so many + different ways. Why be so restricted? Here my solution has been "object + citation numbering". What the various generated document formats have in + common is a shared object numbering system that identifies the location of text + and that is available for citation purposes. Object numbers are: sequential + numbers assigned to each identified object in a document. Objects are logical + units of text (or equivalent parts of a document), usually paragraphs, but also + document headings, tables, images, in a poem a verse etc. [In an electronic + publishing age are page numbers the best we can come up with? Change font + type, font size, page orientation, paper size (sometimes even the viewer) and + where are you with them? And paper though a favorite medium of mine is no + longer the sole (or sometimes primary) means of interacting with documents/text + or of sharing knowledge] + + What object numbers mean (unlike page numbers) is e.g. + + * if you cite text in any format, the resulting output can be reliably located + in any other document format type. Cite HTML and the reader can choose to + view in Epub or Pdf (the PDFs being an independent output, generated by + book publishing software XeTeX/LaTeX). + + * if you do a search, you can be given a result "index" indicating that your + search criteria is met by these documents, and at these specific locations + within each document, and the "index" is relevant not only for content + within the database, but for all document formats. + + * if you have a translated text prepared for sisu, then your citations are + relevant across languages e.g. you can specify exactly where in a Chinese + document text is to be found. + + * generated document index references & concordance list references etc. are + relevant across all output formats. + + What of search? For search, see the implications of object numbers for search + mentioned above. The system currently loads an SQL server (Postgresql) with + object sized text chunks. It could just as well populate an analytical engine + with larger sections or chapters of text for analytical purposes (such as the + currently popular Elasticsearch), whilst availing itself also of the concept of + objects and object numbers in search results. + + How do you deal with multilingual texts? If you have translated text prepared + for sisu, then your citations are relevant across languages. Object numbers + also provide an easy way to compare, discuss text (translations) across + languages. Text found/cited in one language has the same object number in its + translations, a given paragraph will be the same in another language, just + change the language code. (documents are prepared in UTF-8, current language + restrictions are: through use of LaTeX tools, Polyglosia & CJK (Chinese, + Japanese & Korean), and from the fact that sisu parses left to right) + + How are materials prepared for contribution to the collection? (a) The easiest + solution if the system allows is for submission in the format in which work is + authored, usually a word processor, for which odf may be a decent selection. + (b) I have stuck with enhanced plaintext, UTF-8 with minimal markup. Source + documents are prepared in UTF-8 text, with a minimalist native markup to + indicate the document structure (headings and their relative levels), + footnotes, and other document "features". This markup is easily parsable to the + human eye, and plays well with version control systems. Documents are prepared + in a text editor. Front ends such as markup assistants in a word processor that + can save to sisu text format or other tool whist possible do not exist. [(c) + yet another form of submission for collaborative work are wikis which have + shown their strength in efforts such as Wikipedia.] + + The system has proven to be a good testing ground for ideas and is flexible and + extensible. (things that could usefully be done: apart from a front end for + simpler user interaction; feed text to an analytical search engine, like + Elasticsearch/Lucene; it still needs a bibliography parser (auto-generation of + a bibliography from footnotes); and it might be useful to allow rough auto + translation documents on the fly by passing text through a translator (such as + Google translate)). + + In any event, my resulting technical opinions (in my modest domain of + action) may be regarded as encapsulated within SiSU + [http://www.sisudoc.org/] + + http://www.sisudoc.org/ + http://www.jus.uio.no/sisu/ + + git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream + http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary + (there may be additional commits in the upstream branch) + git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream + + git clone git://git.sisudoc.org/git/doc/sisu-markup-samples.git --branch upstream + git clone --depth 1 git://git.sisudoc.org/git/doc/sisu-markup-samples.git --branch upstream + 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 + + Text can be represented in multiple output formats with different + characteristics that are (or may be) regarded as strengths/advantages and + therefore preferred in different contexts. + + Given the different strengths and characteristics of various output formats, it + makes little sense to try too hard to make different representations of a + document look the same. More interesting is have document representations that + take advantage of each given outputs strengths. As valuable if not more so is + the ability to cite, find, discuss text with ease, across the different output + formats. + + For citation across output formats, SiSU uses object citation numbers. + +**** 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? + 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 + +***** What are object citation numbers? + + An object citation number is a sequential number assigned to a document object. + + In sisu output documents share this common object numbering system (dubbed + "object citation numbering" (ocn)) that is meaningful (machine & human readable) + across various digital outputs whether paper, screen, or database oriented, + (PDF, html, XML, EPUB, sqlite, postgresql), and across multilingual content if + prepared appropriately. This numbering system can be used to reference content + across output types. + +***** 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). + + In this digital & Internet age we have multiple ways to represent documents and + multiple document output formats as options with different characteristics, + strengths/advantages etc. We need a way to cite text that works and is relevant + independent of the document format used. + + I want to discuss (cite) html text how do I do this? + how do I refer to / cite / discuss text in html? + Issue: html may be viewed online or printed, it is not tied to paper (as + e.g. pdf) and prints differently depending on selected font face and font size. + + I want to discuss (cite) text that is available in multiple formats (e.g. pdf, + epub, html) without having to worry about the output format that is referred + to. + How do I refer to / discuss text that is available in more than one format, + uncertain of what format is preferred, used or available to my colleagues? + e.g. html and epub or pdf have rather different text representations, how do I + discuss ... + + I would like to have a book index that is relevant (can be used) across multiple + output formats (e.g. pdf, epub, html) + + How do I make a book index (or a concordance file) that works across multiple + output formats? + + I would like to have search results indicating where in a document matches are + found and I would like it to be relevant across available output formats (e.g. + pdf, epub, html) + How do I get search results for locations of text within each relevant document + + I would like to be able to discuss a text that has been translated ... + how do I find text across languages? + Where I have a nicely translated document, how do I point to or discuss with my + 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 + + 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 + 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 + SiSU information Structuring Universe + Structured information, Serialized Units <www.sisudoc.org> or + <www.jus.uio.no/sisu/> software for electronic texts, document collections, + books, digital libraries, and search, with "atomic search" and text positioning + 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 is a comprehensive future-resilient electronic document management system. + Built-in search capabilities allow you to search across multiple documents and + highlight matches in an easy-to-follow format. Paragraph numbering system + allows you to cite your electronic documents in a consistent manner across + multiple file formats. Multiple format outputs allow you to display your + documents in plain text, PDF (portrait and horizontal), OpenDocument format, + HTML, or e-book reading format (EPUB). Word mapping allows you to easily create + word indexes for your documents. Future-resilient flexibility allows you to + quickly adapt your documents to newer output formats as needed. All these and + many other features are achieved with little or no additional work on your + documents - by marking up the documents with a super simplistic markup + language, leaving the SiSU engine to handle the heavy-lifting processing. + + Potential users of SiSU include individual authors who want to publish their + books or articles electronically to reach a broad audience, web publishers who + want to provide multiple channels of access to their electronic documents, or + any organizations which centrally manage a medium or large set of electronic + documents, especially governmental organizations which may prefer to keep their + documents in easily accessible yet non-proprietary formats. + + SiSU is an Open Source project initiated and led by Ralph Amissah + <ralph.amissah@gmail.com> and can be contacted via mailing list + <http://lists.sisudoc.org/listinfo/sisu> at <sisu@lists.sisudoc.org>. SiSU is + licensed under the GNU General Public License. + +***** notes + + For less markup than the most elementary HTML you can have more. SiSU - + Structured information, Serialized Units for electronic documents, is an + information structuring, transforming, publishing and search framework with the + following features: + + (i) markup syntax: (a) simpler than html, (b) mnemonic, influenced by + mail/messaging/wiki markup practices, (c) human readable, and easily writable, + + (ii) (a) minimal markup requirement, (b) single file marked up for multiple outputs, + + * documents are prepared in a single UTF-8 file using a minimalistic mnemonic + syntax. Typical literature, documents like "War and Peace" require almost no + markup, and most of the headers are optional. + + * markup is easily readable/parsed by the human eye, (basic markup is simpler + and more sparse than the most basic html), [this may also be converted to XML + representations of the same input/source document]. + + * markup defines document structure (this may be done once in a header + pattern-match description, or for heading levels individually); basic text + attributes (bold, italics, underscore, strike-through etc.) as required; and + semantic information related to the document (header information, extended + beyond the Dublin core and easily further extended as required); the headers + may also contain processing instructions. + + (iii) (a) multiple output formats, including amongst others: plaintext (UTF-8); + html; (structured) XML; ODF (Open Document text); EPUB; LaTeX; PDF (via LaTeX); + SQL type databases (currently PostgreSQL and SQLite). SiSU produces: + concordance files; document content certificates (md5 or sha256 digests of + headings, paragraphs, images etc.) and html manifests (and sitemaps of + content). (b) takes advantage of the strengths implicit in these very different + output types, (e.g. PDFs produced using typesetting of LaTeX, databases + populated with documents at an individual object/paragraph level, making + possible granular search (and related possibilities)) + + (iv) outputs share a common numbering system (dubbed "object citation + numbering" (ocn)) that is meaningful (to man and machine) across various + digital outputs whether paper, screen, or database oriented, (PDF, html, XML, + EPUB, sqlite, postgresql), this numbering system can be used to reference + content. + + (v) SQL databases are populated at an object level (roughly headings, + paragraphs, verse, tables) and become searchable with that degree of + granularity, the output information provides the object/paragraph numbers which + are relevant across all generated outputs; it is also possible to look at just + the matching paragraphs of the documents in the database; [output indexing also + work well with search indexing tools like hyperesteier]. + + (vi) use of semantic meta-tags in headers permit the addition of semantic + information on documents, (the available fields are easily extended) + + (vii) creates organised directory/file structure for (file-system) output, + easily mapped with its clearly defined structure, with all text objects + numbered, you know in advance where in each document output type, a bit of text + will be found (e.g. from an SQL search, you know where to go to find the + prepared html output or PDF etc.)... there is more; easy directory management + and document associations, the document preparation (sub-)directory may be used + to determine output (sub-)directory, the skin used, and the SQL database used, + + (viii) "Concordance file" wordmap, consisting of all the words in a document + and their (text/ object) locations within the text, (and the possibility of + adding vocabularies), + + (ix) document content certification and comparison considerations: (a) the + document and each object within it stamped with an sha256 hash making it + possible to easily check or guarantee that the substantive content of a document + is unchanged, (b) version control, documents integrated with time based source + control system, default RCS or CVS with use of $Id$ tag, which SiSU checks + + (x) SiSU's minimalist markup makes for meaningful "diffing" of the substantive + content of markup-files, + + (xi) easily skinnable, document appearance on a project/site wide, directory + wide, or document instance level easily controlled/changed, + + (xii) in many cases a regular expression may be used (once in the document + header) to define all or part of a documents structure obviating or reducing + the need to provide structural markup within the document, + + (xiii) prepared files may be batch process, documents produced are static files + so this needs to be done only once but may be repeated for various reasons as + desired (updated content, addition of new output formats, updated technology + document presentations/representations) + + (xiv) possible to pre-process, which permits: the easy creation of standard + form documents, and templates/term-sheets, or; building of composite documents + (master documents) from other sisu marked up documents, or marked up parts, + i.e. import documents or parts of text into a main document should this be + desired + + there is a considerable degree of future-resilience, output representations are + "upgradeable", and new document formats may be added. + + (xv) there is a considerable degree of future-resilience, output representations + are "upgradeable", and new document formats may be added: (a) modular, (thanks + in no small part to Ruby) another output format required, write another + module.... (b) easy to update output formats (eg html, XHTML, LaTeX/PDF + produced can be updated in program and run against whole document set), (c) + easy to add, modify, or have alternative syntax rules for input, should you + need to, + + (xvi) scalability, dependent on your file-system (ext3, Reiserfs, XFS, + whatever) and on the relational database used (currently Postgresql and + SQLite), and your hardware, + + (xvii) only marked up files need be backed up, to secure the larger document + set produced, + + (xviii) document management, + + (xix) Syntax highlighting for SiSU markup is available for a number of text + editors. + + (xx) remote operations: (a) run SiSU on a remote server, (having prepared sisu + markup documents locally or on that server, i.e. this solution where sisu is + installed on the remote server, would work whatever type of machine you chose + to prepare your markup documents on), (b) generated document outputs may be + posted by sisu to remote sites (using rsync/scp) (c) document source (plaintext + utf-8) if shared on the net may be identified by its url and processed locally + to produce the different document outputs. + + (xxi) document source may be bundled together (automatically) with associated + documents (multiple language versions or master document with inclusions) and + images and sent as a zip file called a sisupod, if shared on the net these too + may be processed locally to produce the desired document outputs, these may be + downloaded, shared as email attachments, or processed by running sisu against + them, either using a url or the filename. + + (xxii) for basic document generation, the only software dependency is Ruby, and + a few standard Unix tools (this covers plaintext, html, XML, ODF, EPUB, LaTeX). + To use a database you of course need that, and to convert the LaTeX generated + to PDF, a LaTeX processor like tetex or texlive. + + as a developers tool it is flexible and extensible + +**** description + + SiSU ("SiSU information Structuring Universe" or "Structured information, + Serialized Units"),1 is a Unix command line oriented framework for document + structuring, publishing and search. Featuring minimalistic markup, multiple + standard outputs, a common citation system, and granular search. Using markup + applied to a document, SiSU can produce plain text, HTML, XHTML, XML, + OpenDocument, LaTeX or PDF files, and populate an SQL database with objects2 + (equating generally to paragraph-sized chunks) so searches may be performed and + matches returned with that degree of granularity (e.g. your search criteria is + met by these documents and at these locations within each document). Document + output formats share a common object numbering system for locating content. + This 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. How it works + + SiSU markup is fairly minimalistic, it consists of: a (largely optional) + document header, made up of information about the document (such as when it was + published, who authored it, and granting what rights) and any processing + instructions; and markup within text which is related to document structure and + typeface. SiSU must be able to discern the structure of a document, (text + headings and their levels in relation to each other), either from information + provided in the instruction header or from markup within the text (or from a + combination of both). Processing is done against an abstraction of the document + comprising of information on the document's structure and its objects,2 which + the program serializes (providing the object numbers) and which are assigned + hash sum values based on their content. This abstraction of information about + document structure, objects, (and hash sums), provides considerable flexibility + in representing documents different ways and for different purposes (e.g. + search, document layout, publishing, content certification, concordance etc.), + and makes it possible to take advantage of some of the strengths of established + ways of representing documents, (or indeed to create new ones). + + 1. also chosen for the meaning of the Finnish term "sisu". + + 2 objects include: headings, paragraphs, verse, tables, images, but not + footnotes/endnotes which are numbered separately and tied to the object from + which they are referenced. + + More information on SiSU provided at: <www.sisudoc.org/sisu/SiSU> + + SiSU was developed in relation to legal documents, and is strong across a wide + variety of texts (law, literature...(humanities, law and part of the social + sciences)). SiSU handles images but is not suitable for formulae/ statistics, + or for technical writing at this time. + + SiSU has been developed and has been in use for several years. Requirements to + cover a wide range of documents within its use domain have been explored. + + <ralph@amissah.com> + <ralph.amissah@gmail.com> + <sisu@lists.sisudoc.org> + <http://lists.sisudoc.org/listinfo/sisu> + 2010 + w3 since October 3 1993 +*** Finding SiSU +**** source + http://git.sisudoc.org/gitweb/ + +***** sisu + sisu git repo: + http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary + +****** most recent source without repo history + git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream +****** full clone + git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream + +***** sisu-markup-samples git repo: + http://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary + +**** mailing list + sisu at lists.sisudoc.org + http://lists.sisudoc.org/listinfo/sisu + +**** irc oftc #sisu + +**** home pages + <http://www.sisudoc.org/> + <http://search.sisudoc.org/> + <http://www.jus.uio.no/sisu> + +*** Installation + +**** where you take responsibility for having the correct dependencies + + Provided you have *Ruby*, *SiSU* can be run. + + SiSU should be run from the directory containing your sisu marked up document + set. + + This works fine so long as you already have sisu external dependencies in + place. For many operations such as html, epub, odt this is likely to be fine. + 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 SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING) + .......................................................... + +****** 1. Obtain the latest sisu source + + using git: + + http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary + http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=log + + git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream + git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream + + or, identify latest available source: + + https://packages.debian.org/sid/sisu + http://packages.qa.debian.org/s/sisu.html + http://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org + + http://sisudoc.org/sisu/archive/pool/main/s/sisu/ + + and download the: + + sisu_5.4.5.orig.tar.xz + + using debian tool dget: + + The dget tool is included within the devscripts package + https://packages.debian.org/search?keywords=devscripts + to install dget install devscripts: + + apt-get install devscripts + + and then you can get it from Debian: + dget -xu http://ftp.fi.debian.org/debian/pool/main/s/sisu/sisu_5.4.5-1.dsc + + or off sisu repos + dget -x http://www.jus.uio.no/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc + or + dget -x http://sisudoc.org/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc + +****** 2. Unpack the source + + 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). SiSU should be run from the directory containing your sisu + marked up document set. + + ruby ~/sisu-5.4.5/bin/sisu --html -v document_name.sst + + This works fine so long as you already have sisu external dependencies in + place. For many operations such as html, epub, odt this is likely to be fine. + 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) + + (i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install + the gem + + Provided you have ruby & rake, this can be done with the single command: + + rake gem_create_build_install + + to build and install sisu v5 & sisu v6, alias gemcbi + + separate gems are made/installed for sisu v5 & sisu v6 contained in source. + + to build and install sisu v5, alias gem5cbi: + + rake gem_create_build_install_stable + + to build and install sisu v6, alias gem6cbi: + + rake gem_create_build_install_unstable + + for individual steps (create, build, install) see rake options, rake -T to + specify sisu version for sisu installed via gem + + gem search sisu + + sisu _5.4.5_ --version + + sisu _6.0.11_ --version + + to uninstall sisu installed via gem + + sudo gem uninstall --verbose sisu + + 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> + +***** installation with 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 + +**** Debian install + + *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. + +**** Arch Linux + +*** sisu markup :sisu: + +**** markup :markup: + +***** sisu document parts + - header + - metadata + - make instructionS + - substantive (& other) content + (sisu markup) + - endnotes + (markup within substantive content) + - glossary + (section, special markup) + - bibliography + (section, special markup) + - book index + (markup attached to substantive content objects) + + |---------------------+-----------------------------------------------------------------------+------------------------+--------| + | header | sisu /header markup/ | markup | | + | - metadata | | | | + | - make instructions | | | | + |---------------------+-----------------------------------------------------------------------+------------------------+--------| + | substantive content | sisu /content markup/ | markup | output | + | | headings (providing document structure), paragraphs, | (regular content) | | + | | blocks (code, poem, group, table) | | | + |---------------------+-----------------------------------------------------------------------+------------------------+--------| + | endnotes | markup within substantive content | markup | output | + | | (extracted from sisu /content markup/) | (from regular content) | | + |---------------------+-----------------------------------------------------------------------+------------------------+--------| + | glossary | identify special section, regular /content markup/ | markup | output | + |---------------------+-----------------------------------------------------------------------+------------------------+--------| + | bibliography | identify section, special /bibliography markup/ | markup | output | + |---------------------+-----------------------------------------------------------------------+------------------------+--------| + | book index | extracted from markup attached to related substantive content objects | markup | output | + | | (special tags in sisu /content markup/) | (from regular content) | | + |---------------------+-----------------------------------------------------------------------+------------------------+--------| + | metadata | | (from regular header) | output | + |---------------------+-----------------------------------------------------------------------+------------------------+--------| + +***** structure - headings, levels + - headings (A-D, 1-3) + + 'A~ ' NOTE title level + + 'B~ ' NOTE optional + 'C~ ' NOTE optional + 'D~ ' NOTE optional + + '1~ ' NOTE chapter level + '2~ ' NOTE optional + '3~ ' NOTE optional + + * node + * parent + * children + +***** font face NOTE open & close marks, inline within paragraph + * emphasize '*{ ... }*' NOTE configure whether bold italics or underscore, default bold + * bold '!{ ... }!' + * italics '/{ ... }/' + * underscore '_{ ... }_' + * superscript '^{ ... }^' + * subscript ',{ ... },' + * strike '-{ ... }-' + * add '+{ ... }+' + * monospace '#{ ... }#' + +***** para + NOTE paragraph controls are at the start of a paragraph + * a para is a block of text separated from others by an empty line + * indent + * default, all '_1 ' up to '_9 ' + * first line hang '_1_0 ' + * first line indent further '_0_1 ' + * bullet + [levels 1-6] + '_* ' + '_1* ' + '_2* ' + * numbered list + [levels 1-3] + '# ' + +***** blocks + NOTE text blocks that are not to be treated in the way that ordinary paragraphs would be + * code + * [type of markup if any] + * poem + * group + * alt + * tables + +***** notes (footnotes/ endnotes) + NOTE inline within paragraph at the location where the note reference is to occur + * footnotes '~{ ... }~' + * [bibliography] [NB N/A not implemented] + +***** links, linking + * links - external, web, url + * links - internal + +***** images [multimedia?] + * images + * [base64 inline] [N/A not implemented] + +***** object numbers + * ocn (object numbers) + automatically attributed to substantive objects, paragraphs, tables, blocks, verse (unless exclude marker provided) + +***** contents + * toc (table of contents) + autogenerated from structure/headings information + * index (book index) + built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text + +***** breaks + * line break ' \\ ' inline + * page break, column break ' -\\- ' start of line, breaks a column, starts a new column, if using columns, else breaks the page, starts a new page. + * page break, page new ' =\\= ' start of line, breaks the page, starts a new page. + * horizontal '-..-' start of line, rule page (break) line across page (dividing paragraphs) + +***** book type index + built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text + + #% comment + * comment + + #% misc + * term & definition + +**** syntax highlighting :syntax:highlighting: + +***** vim + data/sisu/conf/editor-syntax-etc/vim/ + data/sisu/conf/editor-syntax-etc/vim/syntax/sisu.vim + +***** emacs + data/sisu/conf/editor-syntax-etc/emacs/ + data/sisu/conf/editor-syntax-etc/emacs/sisu-mode.el + +*** todo + sisu_todo.org + +* document header + +#+NAME: sisu_document_header +#+BEGIN_SRC text +encoding: utf-8 +- Name: SiSU + + - Description: documents, structuring, processing, publishing, search + sisu build + + - Author: Ralph Amissah + <ralph.amissah@gmail.com> + + - Copyright: (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, + 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2019, + 2020, 2021, Ralph Amissah, + All Rights Reserved. + + - License: GPL 3 or later: + + SiSU, a framework for document structuring, publishing and search + + Copyright (C) Ralph Amissah + + This program is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by the Free + Software Foundation, either version 3 of the License, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + more details. + + You should have received a copy of the GNU General Public License along with + this program. If not, see <http://www.gnu.org/licenses/>. + + If you have Internet connection, the latest version of the GPL should be + available at these locations: + <http://www.fsf.org/licensing/licenses/gpl.html> + <http://www.gnu.org/licenses/gpl.html> + + <http://www.sisudoc.org/sisu/en/manifest/gpl.fsf.html> + + - SiSU uses: + - Standard SiSU markup syntax, + - Standard SiSU meta-markup syntax, and the + - Standard SiSU object citation numbering and system + + - Homepages: + <http://www.sisudoc.org> + + - Git + <https://git.sisudoc.org/projects/> + <https://git.sisudoc.org/projects/?p=software/sisu.git;a=summary> + <https://git.sisudoc.org/projects/?p=markup/sisu-markup-samples.git;a=summary> +#+END_SRC |