From 615892da80afb671040c8be5d89430ae2fafe180 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Mon, 30 Jan 2023 21:46:59 -0500 Subject: nix flake, install & devShells etc. --- org/config_build.org | 5943 ++++++++++++++++++++++++++++++++++++++++++++++++ org/config_git.org | 119 + org/config_nix.org | 481 ++++ org/sisu-bin.org | 2 +- org/sisu_build.org | 6181 -------------------------------------------------- 5 files changed, 6544 insertions(+), 6182 deletions(-) create mode 100644 org/config_build.org create mode 100644 org/config_git.org create mode 100644 org/config_nix.org delete mode 100644 org/sisu_build.org (limited to 'org') diff --git a/org/config_build.org b/org/config_build.org new file mode 100644 index 00000000..def24caf --- /dev/null +++ b/org/config_build.org @@ -0,0 +1,5943 @@ +-*- 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 +#+PROPERTY: header-args+ :mkdirp yes + +* 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 + +#+HEADER: :tangle ../setup/sisu_version.rb +#+BEGIN_SRC ruby +#% constants +module SiSUversion + SiSU_version = '7.3.0' +end +module Dev + GPGpubKey = '1BB4B289' +end +#+END_SRC + +* +makefile+ :makefile: + +#+HEADER: :NO-tangle ../makefile +#+BEGIN_SRC makefile +#+END_SRC + +* qi (quick install) +** bin + +#+BEGIN_SRC ruby :tangle ../qi :tangle-mode (identity #o755) :shebang #!/usr/bin/env ruby +=begin + +- Description: + +- Homepage: + +- Copyright: (C) 2015, 2023 Ralph Amissah + +- License: + +- Ralph Amissah + +=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 + +#+HEADER: :tangle ../setup/qi_libs.rb +#+BEGIN_SRC ruby +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 + 'https://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/,'')}) + https://git.sisudoc.org/projects/sisu/tag/?h=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) + https://git.sisudoc.org/projects/sisu/tag/?h=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}' +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}' +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 + +#+HEADER: :tangle ../lib/sisu/sisu_thor_lib.rb +#+BEGIN_SRC ruby +#<> +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 + +#+HEADER: :tangle ../setup/rbuild +#+HEADER: :shebang #!/usr/bin/env ruby +#+HEADER: :tangle-mode (identity #o755) +#+BEGIN_SRC ruby +=begin + Common Rakefile, Rantfile installer for SiSU + softlink Rakefile and Rantfile to this file + + - Homepage: + + Copyright (C) 2007 Ralph Amissah + + - License: LGPL - GNU Lesser General Public License + [same license as Rant provided within the Rant package] + + - Ralph Amissah + + Rake is a Ruby build program by Jim Weirich + - Rake may be downloaded and installed from: + + + Rant is a Ruby build program by Stefan Lang + - Rant may be downloaded and installed from: + + + 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: + + sisu source code is available at: + + + sisu markup samples are provided/packaged separately as sisu-markup-samples: + + 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 + +#+HEADER: :tangle ../setup/rbuild_libs.rb +#+BEGIN_SRC ruby +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/,'')}) +https://git.sisudoc.org/projects/sisu/tag/?h=sisu_#{vi[:version]} +https://git.sisudoc.org/projects/sisu/tag/?h=debian/sisu_#{vi[:version]}-1 + 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 + +#+HEADER: :tangle ../setup/rbuild_help.rb +#+BEGIN_SRC ruby +module Help + def self.project_help + puts < + +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: + + +---------------------------------------- + +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: + + + + 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 https://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: +] +[^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: or + +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 or from + +There is of course this document, which provides a cursory overview of sisu +markup and the respective output produced: + +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}https://sisudoc.org; {git}https://git.sisudoc.org + :footer: {SiSU}https://sisudoc.org; {git}https://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 }https://www.sisudoc.org/ + { SiSU Manual }https://www.sisudoc.org/sisu/sisu_manual/ + { SiSU Git repo }https://git.sisudoc.org/sisu/ + { SiSU @ Debian }https://packages.qa.debian.org/s/sisu.html + { SiSU Project @ Debian }https://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org + { SiSU @ Wikipedia }https://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 }https://www.sisudoc.org + { FSF }https://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}https://sisudoc.org; {git}https://git.sisudoc.org + :footer: {SiSU}https://sisudoc.org; {git}https://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 https://www.sisudoc.org/ continues + +*resulting output:* + +normal text continues + +An escaped url without decoration + +*markup example:* + +normal text _https://www.sisudoc.org/ continues + +deb _https://www.jus.uio.no/sisu/archive unstable main non-free + +*resulting output:* + +normal text https://www.sisudoc.org/ continues + +deb https://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 https://www.jus.uio.no/sisu/archive unstable main non-free +deb-src https://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 }https://url.org markup + +*resulting output:* + +about SiSU [link: ] markup + +A shortcut notation is available so the url link may also be provided +automatically as a footnote + +*markup example:* + +about {~^ SiSU }https://url.org markup + +*resulting output:* + +about SiSU [link: ] [^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" }https://www.ruby-lang.org/en/ + +*resulting output:* + +tux.png 64x80 [link: local image] + +tux.png 64x80 "Gnu/Linux - a better way" [link: ] + +GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian +and Ruby" [link: ] + +ruby_logo.png 70x90 "Ruby" [link: ] [^8] + +*linked url footnote shortcut* + +{~^ [text to link] }https://url.org + +% maps to: { [text to link] }https://url.org ~{ https://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: ] + document manifest [link: ] + html, segmented text [link: ] + html, scroll, document in one [link: ] + epub [link: ] + pdf, landscape [link: ] + pdf, portrait [link: ] + odf: odt, open document text [link: ] + xhtml scroll [link: ] + xml, sax [link: ] + xml, dom [link: ] + concordance [link: ] + dcc, document content certificate (digests) [link: ] + markup source text [link: ] + markup source (zipped) pod [link: ] + +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: https://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: https://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]: + + [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]: + + [8]: + + [9]: Table from the Wealth of Networks by 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 + [https://www.sisudoc.org/] + + https://www.sisudoc.org/ + + git clone git://git.sisudoc.org/software/sisu --branch upstream + https://git.sisudoc.org/sisu/ + (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 or + 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 + and can be contacted via mailing list + at . 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: + + 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. + + + + + + 2010 + w3 since October 3 1993 +*** Finding SiSU +**** source + https://git.sisudoc.org/sisu/ + +***** sisu + sisu git repo: + https://git.sisudoc.org/sisu/ + +****** most recent source without repo history + git clone --depth 1 git://git.sisudoc.org/software/sisu --branch upstream +****** full clone + git clone git://git.sisudoc.org/software/sisu --branch upstream + +***** sisu-markup-samples git repo: + https://git.sisudoc.org/sisu-markup + +**** mailing list + sisu at lists.sisudoc.org + https://lists.sisudoc.org/listinfo/sisu + +**** irc oftc #sisu + +**** home pages + + +*** 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: + + https://git.sisudoc.org/sisu/ + + git clone git://git.sisudoc.org/software/sisu --branch upstream + git clone --depth 1 git://git.sisudoc.org/software/sisu --branch upstream + + or, identify latest available source: + + https://packages.debian.org/sid/sisu + https://packages.qa.debian.org/s/sisu.html + https://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org + + https://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 https://ftp.fi.debian.org/debian/pool/main/s/sisu/sisu_5.4.5-1.dsc + + or off sisu repos + dget -x https://www.jus.uio.no/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc + or + dget -x https://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: + +***** 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: + + + + 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 https://www.jus.uio.no/sisu/archive unstable main non-free + deb-src https://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: + ] + [^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 + +** git +*** gitignore + +#+HEADER: :tangle ../.gitignore +#+BEGIN_SRC sh +# git ls-files --others --exclude-from=.git/info/exclude +* +!README +!COPYRIGHT +!CHANGELOG +!CHANGELOGS/ +!CHANGELOGS/CHANGELOG +!CHANGELOGS/CHANGELOG_v* +!makefile +!Rakefile +!Rantfile +!qi +!setup/ +!setup/* +!version +!version.txt +!conf/ +!conf/** +!*.json +!*.org +!*.rb +!*.txt +!*.yml +!*.nix +!nix/ +!nix/** +!org/ +!bin +!bin/sisu +!bin/sisu-* +!bin/sisugem +!lib +!lib/** +!man +!man/** +!data +!data/doc +!data/doc/** +!data/sisu +!data/sisu/** +!*.sst +!*.ssm +!**/*.sst +!**/*.ssm +!debian/ +!debian/changelog +!debian/compat +!debian/control +!debian/copyright +!debian/gbp.conf +!debian/sisu*.manpages +!debian/sisu*.install +!debian/manpages/ +!debian/manpages/sisu*.7 +!debian/rules +!debian/sisu\.* +!debian/source/ +!debian/source/format +!debian/watch +*~ +*_ +\#* +*.\#* +*.tmp +*_tmp +*.gem +*.gemspec +!sisu.gemspec +*_.rb +*.rb_ +0???-*.patch +*.gz +*.xz +*_ +.* +!.gitignore +!.envrc +#+END_SRC + +##+HEADER: :tangle ../.gitignore +#+BEGIN_SRC sh +# git ls-files --others --exclude-from=.git/info/exclude +,*~ +,*_ +\#* +,*.\#* +,*.tmp +,*_tmp +.* +,*.gem +,*.gemspec +!.gitignore +!.envrc +,*_.rb +,*.rb_ +.pc +0???-*.patch +,*.gz +,*.xz +#+END_SRC + +*** 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 + + + - 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 . + + If you have Internet connection, the latest version of the GPL should be + available at these locations: + + + + + + - SiSU uses: + - Standard SiSU markup syntax, + - Standard SiSU meta-markup syntax, and the + - Standard SiSU object citation numbering and system + + - Homepages: + + + - Git + + + +#+END_SRC diff --git a/org/config_git.org b/org/config_git.org new file mode 100644 index 00000000..88eae7f5 --- /dev/null +++ b/org/config_git.org @@ -0,0 +1,119 @@ +-*- mode: org -*- +#+TITLE: configuration git +#+DESCRIPTION: documents - structuring, various output representations & search +#+FILETAGS: :sisu:configure:git: +#+AUTHOR: Ralph Amissah +#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]] +#+COPYRIGHT: Copyright (C) 2015 - 2023 Ralph Amissah +#+LANGUAGE: en +#+STARTUP: content hideblocks hidestars noindent entitiespretty +#+PROPERTY: header-args :exports code +#+PROPERTY: header-args+ :noweb yes +#+PROPERTY: header-args+ :results no +#+PROPERTY: header-args+ :cache no +#+PROPERTY: header-args+ :padline no +#+PROPERTY: header-args+ :mkdirp yes +#+OPTIONS: H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t + +* git +** .gitignore :gitignore: + +#+HEADER: :tangle "../.gitignore" +#+BEGIN_SRC sh +# git ls-files --others --exclude-from=.git/info/exclude +# git check-ignore -v flake.lock +# git clean -ix +# find . -name "*_" | xargs rm -rf +,* +!nix/** +!*.nix +!flake.lock +!README +!COPYRIGHT +!CHANGELOG +!CHANGELOGS/ +!CHANGELOGS/CHANGELOG +!CHANGELOGS/CHANGELOG_v* +!makefile +!Rakefile +!Rantfile +!qi +!setup/ +!setup/* +!version +!version.txt +!conf/ +!conf/** +!*.json +!*.org +!org/ +!org/*.org +!*.rb +!*.txt +!*.yml +!bin +!bin/sisu +!bin/sisu-* +!bin/sisugem +!lib +!lib/** +!man +!man/** +!data +!data/doc +!data/doc/** +!data/sisu +!data/sisu/** +!*.sst +!*.ssm +!*.ssi +!**/*.sst +!**/*.ssm +!**/*.ssi +!debian/ +!debian/changelog +!debian/compat +!debian/control +!debian/copyright +!debian/gbp.conf +!debian/sisu*.manpages +!debian/sisu*.install +!debian/manpages/ +!debian/manpages/sisu*.7 +!debian/rules +!debian/sisu\.* +!debian/source/ +!debian/source/format +!debian/watch +,*~ +,*_ +\#* +,*.\#* +,*.tmp +,*_tmp +,*.gem +,*.gemspec +!sisu.gemspec +,*_.rb +,*.rb_ +0???-*.patch +,*.gz +,*.xz +,*_ +.* +!.gitignore +!.gitattributes +!.envrc +!.env +!.env/** +#+END_SRC + +** .gitattributes :gitattributes: + +#+HEADER: :tangle "../.gitattributes" +#+BEGIN_SRC sh +/org export-ignore +.gitattributes export-ignore +tangle export-ignore +flake.lock export-ignore +#+END_SRC diff --git a/org/config_nix.org b/org/config_nix.org new file mode 100644 index 00000000..019cac7c --- /dev/null +++ b/org/config_nix.org @@ -0,0 +1,481 @@ +-*- mode: org -*- +#+TITLE: configuration nix +#+DESCRIPTION: makefile for spine +#+FILETAGS: :sisu:build:tools: +#+AUTHOR: Ralph Amissah +#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]] +#+COPYRIGHT: Copyright (C) 2015 - 2023 Ralph Amissah +#+LANGUAGE: en +#+STARTUP: content hideblocks hidestars noindent entitiespretty +#+PROPERTY: header-args :exports code +#+PROPERTY: header-args+ :noweb yes +#+PROPERTY: header-args+ :results no +#+PROPERTY: header-args+ :cache no +#+PROPERTY: header-args+ :padline no +#+PROPERTY: header-args+ :mkdirp yes +#+OPTIONS: H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t + +* nix :nix: + +#+NAME: nixpkgs_local +#+BEGIN_SRC sh +/srv/nix/nixpkgs +#+END_SRC + +- default.nix +- shell.nix + +** envrc :envrc: +*** .envrc + +- https://github.com/nix-community/nix-direnv + - source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/${NixDirEnvVersion}/direnvrc" "sha256-0000000000000000000000000000000000000000000=" + +#+HEADER: :tangle ../.envrc +#+BEGIN_SRC sh +use flake . +#use flake .#default +NIX_ENFORCE_PURITY=1 +NixDirEnvVersion="2.2.1" +if ! has nix_direnv_version || ! nix_direnv_version ${NixDirEnvVersion}; then +# - https://github.com/nix-community/nix-direnv +# source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/${NixDirEnvVersion}/direnvrc" "sha256-0000000000000000000000000000000000000000000=" + source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/${NixDirEnvVersion}/direnvrc" "sha256-zelF0vLbEl5uaqrfIzbgNzJWGmLzCmYAkInj/LNxvKs=" +fi +watch_file flake.lock +watch_file flake.nix +if [ -f .envrc-local ]; then + source_env_if_exists .envrc-local || source .envrc-local +fi +#nix flake update && nix flake check --show-trace && nix flake show +#+END_SRC + +*** .envrc-local CHECK MODIFY + +- bespoke modify appropriately and generate if needed + +#+HEADER: :tangle ../.envrc-local_ +#+HEADER: :noweb yes +#+BEGIN_SRC sh +export NIX_PATH=/nix/var/nix/profiles/per-user/root/channels/nixos +#export NIX_PATH=nixpkgs=/nixpkgs-ra/nixpkgs +## reload when these files change +use flake +watch_file flake.nix +#eval "$(nix print-dev-env)" +export sisuVER=$(git describe --long --tags | sed 's/^[ a-z_-]\+\([0-9.]\+\)/\1/;s/\([^-]*-g\)/r\1/;s/-/./g') +#export sisuBIN=bin +export sisuSRC=~/grotto/repo/git.repo/projects/project-sisu/sisu +export sisuDOC=~/grotto/repo/git.repo/projects/project-sisu/susu-markup/sisu-markup-samples/data/samples/current +export sisuOUT=/var/www +export sisuOUTver=/tmp/sisu/$sisuVER/www +export RUBYLIB+=`pwd`/lib +#+END_SRC + +** flake :flake: +*** flake +**** flake.nix + +#+HEADER: :tangle ../flake.nix +#+HEADER: :noweb yes +#+BEGIN_SRC nix +{ + description = "sisu parser & document generator"; + inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; # "github:nixos/nixpkgs"; "github:NixOS/nixpkgs/nixpkgs-unstable"; "nixpkgs/nixos-unstable"; "nixpkgs/nixos-21.11"; + inputs.flake-utils.url = "github:numtide/flake-utils"; + outputs = { self, nixpkgs, flake-utils } @inputs: + let + pname = "sisu"; + version = "<>"; + shell = ./shell.nix; # ./default.nix; + devEnv = ./.envrc; # ./shell.nix; # ./default.nix; + supportedSystems = [ "x86_64-linux" ]; # [ "x86_64-linux" "x86_64-darwin" "aarch64-linux" "aarch64-darwin" ]; + forAllSystems = nixpkgs.lib.genAttrs supportedSystems; + nixpkgsFor = forAllSystems (system: import nixpkgs { inherit system; }); # nixpkgs instantiated for supported system types. + checkPhase = '' + runHook preCheck + runHook postCheck + ''; + preInstall = '' + mkdir -p $out/lib + mkdir -p $out/bin + ''; + installPhase = '' + runHook preInstall + mkdir -p $out/lib + mkdir -p $out/setup + mkdir -p $out/data + mkdir -p $out/bin + #cp ./lib/sisu.rb $out/lib/sisu.rb + cp -R ./lib/* $out/lib/. + cp -R ./data/* $out/data/. + cp -R ./setup/* $out/setup/. + ln -s $out/setup/sisu_version.rb $out/version + install -m755 ./bin/sisu $out/bin/sisu + runHook postInstall + ''; + postInstall = '' + # echo `ls -la $out/bin/sisu` + ## $out/bin/sisu -v + ''; + in { + packages = forAllSystems (system: + let pkgs = nixpkgsFor.${system}; + in with pkgs; { + default = stdenv.mkDerivation { + inherit pname; + inherit version; + meta.mainProgram = "sisu"; + executable = true; + src = self; + inherit shell; + inherit devEnv; + buildInputs = [ + ruby_3_1 + rubyPackages_3_1.rake + rubyPackages_3_1.sqlite3 + rubyPackages_3_1.thor + #ruby_2_7 + #rubyPackages_2_7.rake + #rubyPackages_2_7.sqlite3 + #rubyPackages_2_7.thor + sqlite + unzip + xz + zip + openssl + nixFlakes + validatePkgConfig + jq + git + sqlite + ]; + buildPhase = '' + ''; + inherit checkPhase; + inherit installPhase; + inherit postInstall; + }; + #vendorSha256 = "sha256-0Q00000000000000000000000000000000000000000="; + }); + apps = forAllSystems (system: { + default = { + type = "app"; + program = "${self.packages.${system}.default}/bin/sisu"; + }; + }); + devShells = forAllSystems (system: + let + pkgs = nixpkgsFor.${system}; + shellHook = '' + export Date=`date "+%Y%m%d"` + export sisuver=$(git describe --long --tags | sed 's/^[ a-z_-]\+\([0-9.]\+\)/\1/;s/\([^-]*-g\)/r\1/;s/-/./g') + ### set local values in .envrc-local (or modify here if you must) + # export sisuPROJ=~/grotto/repo/git.repo/projects/doc-reform/code/software/sisu + # export sisuDOC=~/grotto/repo/git.repo/projects/project-sisu/doc-reform-markup/sisu-markup-samples + # export sisuSRC=~/grotto/repo/git.repo/projects/project-sisu/sisu + # export sisuDOC=~/grotto/repo/git.repo/projects/project-sisu/susu-markup/sisu-markup-samples/data/samples/current + # export sisuOUT=/srv/www/sisu + # export sisuOUTver=/srv/www/sisu/$sisuVER/www + # export sisu=/srv/www/sisu + # export sisu=/var/www/sqlite + # export sisu=/srv/www/sisu/sqlite + export sisu=$sisuPROJ/src + export sisu=$sisuPROJ/result/lib + export sisu=$sisuDOC/markup/pod + export sisu=$sisuOUT/$sisuVER + export sisu='http://localhost/sisu_search' + # export sisuSearchActionRemote='https://sisudoc.org/sisu_search' + export sisuCGIform='sisu_search' + export sisuSQLdb='sisusearch.db' + export PROG_VER_GIT="`git describe --long --tags | sed -e 's/^[ a-z_-]\+\([0-9.]\+\)/\1/;s/\([^-]*-g\)/r\1/;s/-/./g'`" + export PROG_VER_DECLARED="`cat ./views/version.txt | grep --color=never "enum" | sed 's/.\+(\([0-9]\+\),[ \t]\+\([0-9]\+\),[ \t]\+\([0-9]\+\)[ \t]*).\+/\1.\2.\3/g'`" + export sisuNixHelp="cat ./.env/nix-commands" + export sisuTest="nix shell .#default --print-build-logs --command sisu --very-verbose --epub --html --html-link-search --html-link-curate --curate --output=\"\$sisuOUT\" $sisuPOD/*" + export sisuHtml="sisu --very-verbose --html --html-link-search --html-link-curate --curate --sqlite-update --sqlite-db-filename=\"sisu.search.db\" --cgi-sqlite-search-filename=\"sisu_search\" --sqlite-db-path=\"\$sisuDBpath\" --output=\"\$sisuOUT\" $sisuPOD/*" + export sisuEpub="sisu --very-verbose --epub --output=\"\$sisuOUT\" $sisuPOD/*" + export sisuLatex="sisu --very-verbose --latex --output=\"\$sisuOUT\" $sisuPOD/*" + export sisuPdf="sisu --very-verbose --pdf --output=\"\$sisuOUT\" $sisuPOD/*" + export sisuSqliteCreateDB="sisu --very-verbose --sqlite-db-recreate --sqlite-db-path=\"$sisuDBpath\" --sqlite-db-filename=\"sisu.search.db\"" + export sisuSqlite="sisu --very-verbose --sqlite-discrete --sqlite-db-path=\"$sisuDBpath\" --sqlite-db-filename=\"sisu.search.db\" --output=\"\$sisuOUT\" $sisuPOD/*" + #export sisuSqlite="sisu --very-verbose --sqlite-update --sqlite-db-path=\"$sisuDBpath\" --sqlite-db-filename=\"sisu.search.db\" --output=\"\$sisuOUT\" $sisuPOD/*" + ''; + in with pkgs; { + devShell = mkShell rec { + name = "sisu dev shell default"; + inherit shell; + inherit devEnv; + packages = [ sqlite ]; + inherit shellHook; + }; + devShell-epub = mkShell rec { + name = "sisu dev shell for epub output"; + inherit shell; + inherit devEnv; + packages = [ + ruby_3_1 + rubyPackages_3_1.rake + rubyPackages_3_1.sqlite3 + rubyPackages_3_1.thor + sqlite + zip + unzip + xz + libxml2 + html-tidy + xmlstarlet + epubcheck + ebook_tools + libxml2 + html-tidy + xmlstarlet + epubcheck + ebook_tools + epr + sigil + calibre #(suite includes: ebook-viewer) + foliate + devenv + nixFlakes + validatePkgConfig + jq + git + ]; + inherit shellHook; + }; + devShell-html = mkShell rec { + name = "sisu dev shell for latex & pdf output"; + inherit shell; + inherit devEnv; + packages = [ + ruby_3_1 + rubyPackages_3_1.rake + rubyPackages_3_1.sqlite3 + rubyPackages_3_1.thor + sqlite + zip + unzip + xz + devenv + nixFlakes + validatePkgConfig + jq + git + ]; + inherit shellHook; + }; + devShell-latex-pdf = mkShell rec { + name = "sisu dev shell for latex & pdf output"; + inherit shell; + inherit devEnv; + packages = [ + ruby_3_1 + rubyPackages_3_1.rake + rubyPackages_3_1.sqlite3 + rubyPackages_3_1.thor + sqlite + zip + unzip + xz + source-sans-pro + source-serif-pro + source-code-pro + texlive.combined.scheme-full + devenv + nixFlakes + validatePkgConfig + jq + git + ]; + inherit shellHook; + }; + devShell-sqlite = mkShell rec { + name = "sisu dev shell for latex & pdf output"; + inherit shell; + inherit devEnv; + packages = [ + ruby_3_1 + rubyPackages_3_1.rake + rubyPackages_3_1.sqlite3 + rubyPackages_3_1.thor + sqlite + zip + unzip + xz + devenv + nixFlakes + validatePkgConfig + jq + git + ]; + inherit shellHook; + }; + devShell-i18n = mkShell { + name = "sisu dev shell internationalization, po4a"; + inherit shell; + inherit devEnv; + packages = [ + ruby_3_1 + rubyPackages_3_1.rake + rubyPackages_3_1.sqlite3 + rubyPackages_3_1.thor + sqlite + perl534Packages.Po4a + devenv + nixFlakes + validatePkgConfig + jq + git + ]; + inherit shellHook; + }; + }); + }; +} +#+END_SRC + +** shell.nix TODO + +#+HEADER: :tangle ../shell.nix +#+HEADER: :shebang #!/usr/bin/env -S nix-shell --pure +#+HEADER: :tangle-mode (identity #o755) +#+BEGIN_SRC nix +{ pkgs ? import {} }: +with pkgs; +mkShell { + buildInputs = [ + <> + <> + <> + <> + ]; + shellHook = '' + if [[ -e ".envrc" ]]; then + source .envrc + fi + eval "$(starship init bash)" + ''; +} +#+END_SRC + +** packages.nix +*** default + +#+HEADER: :NO-tangle ../packages.nix +#+BEGIN_SRC nix +{ pkgs ? import {} }: +with pkgs; [ + <> + <> + <> +] +#+END_SRC + +*** ruby 3.1 + +#+HEADER: :tangle ../nix/pkglst/packages_ruby_3_1.nix +#+BEGIN_SRC nix +{ pkgs ? import {} }: +with pkgs; [ + <> + <> + <> +] +#+END_SRC + +*** ruby 3.0 + +#+HEADER: :tangle ../nix/pkglst/packages_ruby_3_0.nix +#+BEGIN_SRC nix +{ pkgs ? import {} }: +with pkgs; [ + <> + <> + <> +] +#+END_SRC + +*** ruby legacy + +#+NAME: ruby_legacy +#+BEGIN_SRC nix +<> +#+END_SRC + +*** ruby current + +#+NAME: ruby_current +#+BEGIN_SRC nix +<> +#+END_SRC + +*** ruby next + +#+NAME: ruby_next +#+BEGIN_SRC nix +<> +#+END_SRC + +*** ruby 3.0 - ruby_version_3_0 + +#+NAME: ruby_version_3_0 +#+BEGIN_SRC nix +ruby_3_0 +rubyPackages_3_0.rake +rubyPackages_3_0.sqlite3 +rubyPackages_3_0.thor +#+END_SRC + +*** ruby 3.1 - ruby_version_3_1 + +#+NAME: ruby_version_3_1 +#+BEGIN_SRC nix +ruby_3_1 +rubyPackages_3_1.rake +rubyPackages_3_1.sqlite3 +rubyPackages_3_1.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 +openssl +#texlive-combined-full +#+END_SRC + +*** project misc build packages + +#+NAME: packages_build +#+BEGIN_SRC nix +nixFlakes +validatePkgConfig +jq +git +#+END_SRC + +#+NAME: packages_extra +#+BEGIN_SRC nix +starship +#+END_SRC + +** variables +** spine version SET VERSION :version:set:project: + +#+NAME: sisu_version_set +#+BEGIN_SRC sh +0.7.3 +#+END_SRC diff --git a/org/sisu-bin.org b/org/sisu-bin.org index 1ee0d567..52ad8ec7 100644 --- a/org/sisu-bin.org +++ b/org/sisu-bin.org @@ -26,7 +26,7 @@ <> #+END_SRC -#+NAME: sisu_version_current_set +#+NAME: sisu_project_version_current_set #+BEGIN_SRC yaml --- :project: SiSU diff --git a/org/sisu_build.org b/org/sisu_build.org deleted file mode 100644 index 37463bff..00000000 --- a/org/sisu_build.org +++ /dev/null @@ -1,6181 +0,0 @@ --*- 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 -#+PROPERTY: header-args+ :mkdirp yes - -* 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 - -#+HEADER: :tangle ../setup/sisu_version.rb -#+BEGIN_SRC ruby -#% constants -module SiSUversion - SiSU_version = '7.3.0' -end -module Dev - GPGpubKey = '1BB4B289' -end -#+END_SRC - -* +makefile+ :makefile: - -#+HEADER: :NO-tangle ../makefile -#+BEGIN_SRC makefile -#+END_SRC - -* qi (quick install) -** bin - -#+BEGIN_SRC ruby :tangle ../qi :tangle-mode (identity #o755) :shebang #!/usr/bin/env ruby -=begin - -- Description: - -- Homepage: - -- Copyright: (C) 2015, 2023 Ralph Amissah - -- License: - -- Ralph Amissah - -=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 - -#+HEADER: :tangle ../setup/qi_libs.rb -#+BEGIN_SRC ruby -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 - 'https://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/,'')}) - https://git.sisudoc.org/projects/sisu/tag/?h=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) - https://git.sisudoc.org/projects/sisu/tag/?h=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}' -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}' -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 - -#+HEADER: :tangle ../lib/sisu/sisu_thor_lib.rb -#+BEGIN_SRC ruby -#<> -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 - -#+HEADER: :tangle ../setup/rbuild -#+HEADER: :shebang #!/usr/bin/env ruby -#+HEADER: :tangle-mode (identity #o755) -#+BEGIN_SRC ruby -=begin - Common Rakefile, Rantfile installer for SiSU - softlink Rakefile and Rantfile to this file - - - Homepage: - - Copyright (C) 2007 Ralph Amissah - - - License: LGPL - GNU Lesser General Public License - [same license as Rant provided within the Rant package] - - - Ralph Amissah - - Rake is a Ruby build program by Jim Weirich - - Rake may be downloaded and installed from: - - - Rant is a Ruby build program by Stefan Lang - - Rant may be downloaded and installed from: - - - 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: - - sisu source code is available at: - - - sisu markup samples are provided/packaged separately as sisu-markup-samples: - - 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 - -#+HEADER: :tangle ../setup/rbuild_libs.rb -#+BEGIN_SRC ruby -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/,'')}) -https://git.sisudoc.org/projects/sisu/tag/?h=sisu_#{vi[:version]} -https://git.sisudoc.org/projects/sisu/tag/?h=debian/sisu_#{vi[:version]}-1 - 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 - -#+HEADER: :tangle ../setup/rbuild_help.rb -#+BEGIN_SRC ruby -module Help - def self.project_help - puts < {} }: -with pkgs; -mkShell { - buildInputs = [ - <> - <> - <> - <> - ]; - shellHook = '' - if [[ -e ".envrc" ]]; then - source .envrc - fi - eval "$(starship init bash)" - ''; -} -#+END_SRC - -#+BEGIN_SRC nix -#!/usr/bin/env -S nix-shell --pure -{ pkgs ? import {} }: -with pkgs; -mkShell { - buildInputs = [ - ruby_3_1 - rubyPackages_3_1.rake - rubyPackages_3_1.sqlite3 - rubyPackages_3_1.thor - sqlite - unzip - xz - zip - openssl - #texlive-combined-full - nixFlakes - validatePkgConfig - jq - git - ### candy - starship - ]; - shellHook = '' - if [[ -e ".envrc" ]]; then - source .envrc - fi - eval "$(starship init bash)" - ''; -} -#+END_SRC - - -#+HEADER: :NO-tangle ../shell.nix -#+BEGIN_SRC nix -{ pkgs ? import {} }: -pkgs.mkShell { - buildInputs = [ - (import ./packages.nix { inherit pkgs; }) - ]; -} -#+END_SRC - -*** packages.nix -**** default - -#+HEADER: :NO-tangle ../packages.nix -#+BEGIN_SRC nix -{ pkgs ? import {} }: -with pkgs; [ - <> - <> - <> -] -#+END_SRC - -**** ruby 3.1 - -#+HEADER: :tangle ../nix/pkglst/packages_ruby_3_1.nix -#+BEGIN_SRC nix -{ pkgs ? import {} }: -with pkgs; [ - <> - <> - <> -] -#+END_SRC - -**** ruby 3.0 - -#+HEADER: :tangle ../nix/pkglst/packages_ruby_3_0.nix -#+BEGIN_SRC nix -{ pkgs ? import {} }: -with pkgs; [ - <> - <> - <> -] -#+END_SRC - -**** ruby 2.6 - -#+HEADER: :tangle ../nix/pkglst/packages_ruby_2_6.nix -#+BEGIN_SRC nix -{ pkgs ? import {} }: -with pkgs; [ - <> - <> - <> -] -#+END_SRC - -*** ruby legacy - -#+NAME: ruby_legacy -#+BEGIN_SRC nix -<> -#+END_SRC -*** ruby current - -#+NAME: ruby_current -#+BEGIN_SRC nix -<> -#+END_SRC - -*** ruby next - -#+NAME: ruby_next -#+BEGIN_SRC nix -<> -#+END_SRC - -*** ruby 2.6 - ruby_version_2_6 - -#+NAME: ruby_version_2_6 -#+BEGIN_SRC nix -ruby_2_6 -rubyPackages_2_6.rake -rubyPackages_2_6.sqlite3 -rubyPackages_2_6.thor -#+END_SRC - -*** ruby 3.0 - ruby_version_3_0 - -#+NAME: ruby_version_3_0 -#+BEGIN_SRC nix -ruby_3_0 -rubyPackages_3_0.rake -rubyPackages_3_0.sqlite3 -rubyPackages_3_0.thor -#+END_SRC - -*** ruby 3.1 - ruby_version_3_1 - -#+NAME: ruby_version_3_1 -#+BEGIN_SRC nix -ruby_3_1 -rubyPackages_3_1.rake -rubyPackages_3_1.sqlite3 -rubyPackages_3_1.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 -openssl -#texlive-combined-full -#+END_SRC - -*** project misc build packages - -#+NAME: packages_build -#+BEGIN_SRC nix -nixFlakes -validatePkgConfig -jq -git -#+END_SRC - -#+NAME: packages_extra -#+BEGIN_SRC nix -starship -#+END_SRC - -* descriptions -** README - -#+HEADER: :tangle ../README -#+BEGIN_SRC md -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: -- - -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: - - ----------------------------------------- - -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: - - - - 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 https://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: -] -[^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: or - -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 or from - -There is of course this document, which provides a cursory overview of sisu -markup and the respective output produced: - -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}https://sisudoc.org; {git}https://git.sisudoc.org - :footer: {SiSU}https://sisudoc.org; {git}https://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 }https://www.sisudoc.org/ - { SiSU Manual }https://www.sisudoc.org/sisu/sisu_manual/ - { SiSU Git repo }https://git.sisudoc.org/sisu/ - { SiSU @ Debian }https://packages.qa.debian.org/s/sisu.html - { SiSU Project @ Debian }https://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org - { SiSU @ Wikipedia }https://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 }https://www.sisudoc.org - { FSF }https://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}https://sisudoc.org; {git}https://git.sisudoc.org - :footer: {SiSU}https://sisudoc.org; {git}https://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 https://www.sisudoc.org/ continues - -*resulting output:* - -normal text continues - -An escaped url without decoration - -*markup example:* - -normal text _https://www.sisudoc.org/ continues - -deb _https://www.jus.uio.no/sisu/archive unstable main non-free - -*resulting output:* - -normal text https://www.sisudoc.org/ continues - -deb https://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 https://www.jus.uio.no/sisu/archive unstable main non-free -deb-src https://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 }https://url.org markup - -*resulting output:* - -about SiSU [link: ] markup - -A shortcut notation is available so the url link may also be provided -automatically as a footnote - -*markup example:* - -about {~^ SiSU }https://url.org markup - -*resulting output:* - -about SiSU [link: ] [^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" }https://www.ruby-lang.org/en/ - -*resulting output:* - -tux.png 64x80 [link: local image] - -tux.png 64x80 "Gnu/Linux - a better way" [link: ] - -GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian -and Ruby" [link: ] - -ruby_logo.png 70x90 "Ruby" [link: ] [^8] - -*linked url footnote shortcut* - -{~^ [text to link] }https://url.org - -% maps to: { [text to link] }https://url.org ~{ https://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: ] - document manifest [link: ] - html, segmented text [link: ] - html, scroll, document in one [link: ] - epub [link: ] - pdf, landscape [link: ] - pdf, portrait [link: ] - odf: odt, open document text [link: ] - xhtml scroll [link: ] - xml, sax [link: ] - xml, dom [link: ] - concordance [link: ] - dcc, document content certificate (digests) [link: ] - markup source text [link: ] - markup source (zipped) pod [link: ] - -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: https://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: https://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]: - - [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]: - - [8]: - - [9]: Table from the Wealth of Networks by 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 - [https://www.sisudoc.org/] - - https://www.sisudoc.org/ - https://www.jus.uio.no/sisu/ - - git clone git://git.sisudoc.org/software/sisu --branch upstream - https://git.sisudoc.org/sisu/ - (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 or - 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 - and can be contacted via mailing list - at . 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: - - 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. - - - - - - 2010 - w3 since October 3 1993 -*** Finding SiSU -**** source - https://git.sisudoc.org/sisu/ - -***** sisu - sisu git repo: - https://git.sisudoc.org/sisu/ - -****** most recent source without repo history - git clone --depth 1 git://git.sisudoc.org/software/sisu --branch upstream -****** full clone - git clone git://git.sisudoc.org/software/sisu --branch upstream - -***** sisu-markup-samples git repo: - https://git.sisudoc.org/sisu-markup - -**** mailing list - sisu at lists.sisudoc.org - https://lists.sisudoc.org/listinfo/sisu - -**** irc oftc #sisu - -**** home pages - - -*** 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: - - https://git.sisudoc.org/sisu/ - - git clone git://git.sisudoc.org/software/sisu --branch upstream - git clone --depth 1 git://git.sisudoc.org/software/sisu --branch upstream - - or, identify latest available source: - - https://packages.debian.org/sid/sisu - https://packages.qa.debian.org/s/sisu.html - https://qa.debian.org/developer.php?login=sisu@lists.sisudoc.org - - https://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 https://ftp.fi.debian.org/debian/pool/main/s/sisu/sisu_5.4.5-1.dsc - - or off sisu repos - dget -x https://www.jus.uio.no/sisu/archive/pool/main/s/sisu/sisu_5.4.5-1.dsc - or - dget -x https://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: - -***** 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: - - - - 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 https://www.jus.uio.no/sisu/archive unstable main non-free - deb-src https://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: - ] - [^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 - -** git -*** gitignore - -#+HEADER: :tangle ../.gitignore -#+BEGIN_SRC sh -# git ls-files --others --exclude-from=.git/info/exclude -* -!README -!COPYRIGHT -!CHANGELOG -!CHANGELOGS/ -!CHANGELOGS/CHANGELOG -!CHANGELOGS/CHANGELOG_v* -!makefile -!Rakefile -!Rantfile -!qi -!setup/ -!setup/* -!version -!version.txt -!conf/ -!conf/** -!*.json -!*.org -!*.rb -!*.txt -!*.yml -!*.nix -!nix/ -!nix/** -!org/ -!bin -!bin/sisu -!bin/sisu-* -!bin/sisugem -!lib -!lib/** -!man -!man/** -!data -!data/doc -!data/doc/** -!data/sisu -!data/sisu/** -!*.sst -!*.ssm -!**/*.sst -!**/*.ssm -!debian/ -!debian/changelog -!debian/compat -!debian/control -!debian/copyright -!debian/gbp.conf -!debian/sisu*.manpages -!debian/sisu*.install -!debian/manpages/ -!debian/manpages/sisu*.7 -!debian/rules -!debian/sisu\.* -!debian/source/ -!debian/source/format -!debian/watch -*~ -*_ -\#* -*.\#* -*.tmp -*_tmp -*.gem -*.gemspec -!sisu.gemspec -*_.rb -*.rb_ -0???-*.patch -*.gz -*.xz -*_ -.* -!.gitignore -!.envrc -#+END_SRC - -##+HEADER: :tangle ../.gitignore -#+BEGIN_SRC sh -# git ls-files --others --exclude-from=.git/info/exclude -,*~ -,*_ -\#* -,*.\#* -,*.tmp -,*_tmp -.* -,*.gem -,*.gemspec -!.gitignore -!.envrc -,*_.rb -,*.rb_ -.pc -0???-*.patch -,*.gz -,*.xz -#+END_SRC - -*** 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 - - - - 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 . - - If you have Internet connection, the latest version of the GPL should be - available at these locations: - - - - - - - SiSU uses: - - Standard SiSU markup syntax, - - Standard SiSU meta-markup syntax, and the - - Standard SiSU object citation numbering and system - - - Homepages: - - - - Git - - - -#+END_SRC -- cgit v1.2.3