aboutsummaryrefslogtreecommitdiffhomepage
path: root/org/config_build.org
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2023-10-30 22:31:28 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2023-10-30 22:31:28 -0400
commitad803956c1f7ce1a4b0e820a21881a58a326b7f7 (patch)
treeeb36cfcd0bcbed76a51b0e97e0a46609769ca232 /org/config_build.org
parentdebian/changelog (7.2.1-2) (diff)
parentversion & changelog, tag for release (diff)
Merge tag 'sisu_7.3.0' into debian
SiSU 7.3.0
Diffstat (limited to 'org/config_build.org')
-rw-r--r--org/config_build.org5837
1 files changed, 5837 insertions, 0 deletions
diff --git a/org/config_build.org b/org/config_build.org
new file mode 100644
index 00000000..6e6e805f
--- /dev/null
+++ b/org/config_build.org
@@ -0,0 +1,5837 @@
+-*- 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: <https://sisudoc.org>
+
+- Copyright: (C) 2015, 2023 Ralph Amissah
+
+- License:
+
+- Ralph Amissah <ralph.amissah@gmail.com>
+
+=end
+#% manual settings, edit/update as required (note current default settings are obtained from sisu version yml file)
+begin
+ require 'thor'
+rescue LoadError
+ puts 'thor (package ruby-thor) not found'
+end
+begin
+ require './setup/sisu_version' # ./setup/sisu_version.rb
+ include SiSUversion
+rescue LoadError
+ puts 'this does not appear to be a SiSU development directory'
+ exit
+end
+require_relative 'setup/qi_libs' # setup/qi_libs.rb
+require 'find'
+require 'fileutils'
+ include FileUtils
+require 'pathname'
+require 'rbconfig.rb'
+require 'yaml'
+module SiSUconf
+ class Configure < Thor
+ class_option :verbose, :type => :boolean
+ desc 'setup --all --bin --lib --conf --data --alt --dryrun',
+ 'setup sisu'
+ options \
+ :all => :boolean,
+ :bin => :boolean,
+ :lib => :boolean,
+ :conf => :boolean,
+ :data => :boolean,
+ :share => :boolean,
+ :man => :boolean,
+ :vim => :boolean,
+ :alt => :boolean,
+ :dryrun => :boolean,
+ :is => :boolean
+ def setup
+ unless options.length >= 1 \
+ and not (options[:bin] \
+ or options[:lib] \
+ or options[:conf] \
+ or options[:data] \
+ or options[:share] \
+ or options[:man] \
+ or options[:vim])
+ puts 'setup --all --bin --lib --conf --data --share --man --vim'
+ end
+ act=(options[:dryrun]) ? (:dryrun) : (:action)
+ if options[:is]
+ puts Version_info.version_number_info_stable
+ end
+ if not options[:alt]
+ if options[:all] \
+ or options[:bin]
+ exclude_files=['sisugem']
+ Install.setup_find_create(
+ 'bin',
+ Project_details.dir.bin,
+ exclude_files,
+ act
+ ) if File.directory?('bin')
+ end
+ if options[:all] \
+ or options[:lib]
+ Install.setup_find_create(
+ 'lib',
+ Project_details.dir.lib,
+ act
+ ) if File.directory?('lib')
+ end
+ if options[:all] \
+ or options[:conf]
+ Install.setup_find_create(
+ 'conf',
+ Project_details.dir.conf,
+ act
+ ) if File.directory?('conf')
+ end
+ if options[:all] \
+ or options[:data]
+ Install.setup_find_create(
+ 'data',
+ Project_details.dir.data,
+ act
+ ) if File.directory?('data')
+ end
+ if options[:all] \
+ or options[:share]
+ Install.setup_find_create(
+ 'data/sisu',
+ Project_details.dir.share,
+ act
+ ) if File.directory?('data/sisu')
+ end
+ if options[:all] \
+ or options[:man]
+ Install.setup_find_create(
+ 'man',
+ Project_details.dir.man,
+ act
+ ) if File.directory?('man')
+ end
+ if options[:all] \
+ or options[:vim]
+ Install.setup_find_create(
+ 'data/vim',
+ Project_details.dir.vim,
+ act
+ ) if File.directory?('data/vim')
+ end
+ else
+ if options[:all] \
+ or options[:bin]
+ Install.setup_find_cp_r(
+ 'bin',
+ Project_details.dir.bin,
+ act
+ ) if File.directory?('bin')
+ end
+ if options[:all] \
+ or options[:bin]
+ Install.setup_find_cp_r(
+ 'lib',
+ Project_details.dir.lib,
+ act
+ ) if File.directory?('lib')
+ end
+ if options[:all] \
+ or options[:conf]
+ Install.setup_find_cp_r(
+ 'conf',
+ Project_details.dir.conf,
+ act
+ ) if File.directory?('conf')
+ end
+ if options[:all] \
+ or options[:data]
+ Install.setup_find_cp_r(
+ 'data',
+ Project_details.dir.data,
+ act
+ ) if File.directory?('data')
+ end
+ if options[:all] \
+ or options[:share]
+ Install.setup_find_cp_r(
+ 'data/sisu',
+ Project_details.dir.share,
+ act
+ ) if File.directory?('data/sisu') #
+ end
+ if options[:all] \
+ or options[:man]
+ Install.setup_find_cp_r(
+ 'man',
+ Project_details.dir.man,
+ act
+ ) if File.directory?('man')
+ end
+ #if options[:all] \
+ #or options[:vim]
+ # Install.setup_find_cp_r('data/vim',"#{Project_details.dir.data}/vim") \
+ # if File.directory?('data/vim')
+ #end
+ end
+ end
+ desc 'pkg',
+ 'package maintenance tasks, ' \
+ + 'of no general interest ' \
+ + '(maintainer specific for package maintainer\'s convenience)'
+ options \
+ :open_version=> :boolean,
+ :version_and_tag_for_release=> :boolean,
+ :tip => :boolean,
+ :is => :boolean
+ def pkg
+ if options[:is]
+ puts Version_info.version_number_info_stable
+ end
+ if options[:tip]
+ Package.sequence
+ end
+ if options[:open_version]
+ Version_info::Update.update_documentation
+ Version_info::Update.update_stable(:pre_release)
+ Version_info::Update.update_pkgbuild_stable(:pre_release)
+ Version_info::Update.changelog_header_stable_pre_release
+ Version_info::Update.changelog_header_commit(:pre_release)
+ end
+ if options[:version_and_tag_for_release]
+ Version_info::Update.update_documentation
+ Version_info::Update.update_stable(:release)
+ Version_info::Update.update_pkgbuild_stable(:release)
+ Version_info::Update.changelog_header_stable
+ Version_info::Update.changelog_header_commit_tag_upstream(:release)
+ end
+ if options.length == 0
+ system("#{$called_as} help pkg")
+ system("#{$called_as} pkg --tip")
+ end
+ end
+ desc 'gem --create --build --install',
+ 'gem create build and install'
+ options \
+ :create => :boolean,
+ :build => :boolean,
+ :install => :boolean,
+ :git_version_number => :boolean,
+ :is => :boolean
+ def gem
+ if options[:is]
+ puts Version_info.version_number_info_stable
+ end
+ if options[:create]
+ version=(options[:git_version_number]) \
+ ? :version_git
+ : :version_standard
+ Gemspecs::Current.create_stable(version)
+ puts 'created gemspec' \
+ if options[:verbose]
+ end
+ if options[:build]
+ Gemspecs::Current.build_stable
+ puts 'built gem' \
+ if options[:verbose]
+ end
+ if options[:install]
+ version=(options[:git_version_number]) \
+ ? :version_git
+ : :version_standard
+ Gemspecs::Current.install_stable(version)
+ puts 'installed gem, version: stable' \
+ if options[:verbose]
+ end
+ unless options.length > 0
+ system("#{$called_as} help gem")
+ end
+ end
+ end
+end
+begin
+ $called_as,$argv=$0,$*
+ SiSUconf::Configure.start(ARGV)
+rescue
+end
+__END__
+#+END_SRC
+
+** qi_lib
+
+#+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
+#<<sisu_document_header>>
+module SiSU_Po4a_Actions
+ require_relative 'utils_response' # utils_response.rb
+ include SiSU_Response
+ @@source=@@targets=nil
+ def project_details
+ def name
+ 'SiSU translations under po4a management'
+ end
+ def name_warning
+ <<-WOK
+#{name}
+
+WARNING all sisu markup files (.ssm, .sst, .ssi) in languages other than #{language.source_language_selected}
+are managed by po4a, through translations of the source language to other languages.
+
+#{language.info_on_selection}
+ WOK
+ end
+ def setup_project
+ "Setup file for placing #{name}"
+ end
+ self
+ end
+ def notice
+ def warn_and_proceed?
+ '*WARNING* this software module creates, destroys, overwrites directories' + "\n" \
+ + '*WARNING*: Use this Software at your own risk!'
+ end
+ def default(selection=nil)
+ selections=:strict #selections=:short
+ ans=if selection
+ case selection
+ when selection.is_a?(String)
+ selections=:strict
+ <<-WOK
+ #{project_details.setup_project}
+ Default action selected - "#{selection} #{project_details.name}"
+#{warn_and_proceed?}
+ WOK
+ when :make
+ selections=:strict
+ <<-WOK
+ #{project_details.setup_project}
+ "--#{selection}" selected - #{selection} #{project_details.name}
+ selected (or configured) languages to be used
+ source language: #{language.source_language_available_str}
+ target languages: #{language.translation_languages_selected_that_are_available.inspect}
+
+ WARNING: this action assumes (and places) this project is under po4a
+ (translation) management. It will create sub-directories for the
+ selected (or configured) target languages:
+ #{language.translation_languages_selected_that_are_available.inspect}
+ & the po4a configuration file: #{filename.po4a_cfg}
+ in the current directory:
+ #{Dir.pwd}
+ It will populate the sub-directories with translation files created from
+ the pot and po files found under the corresponding language
+ sub-directories, (under #{dir.pot}/ & #{dir.po}/).
+ (OVERWRITING any existing translated .ssm .sst .ssi files
+ in language subdirectories that are not under po4a management).
+
+ You should backup the current directory:
+ #{Dir.pwd}
+
+#{warn_and_proceed?}
+ WOK
+ when :clean
+ selections=:strict
+ <<-WOK
+ #{project_details.setup_project}
+ "--#{selection}" selected - #{selection} #{project_details.name}
+#{warn_and_proceed?}
+ WOK
+ when :distclean
+ selections=:strict
+ <<-WOK
+ #{project_details.setup_project}
+ "--#{selection}" selected - #{selection} #{project_details.name}
+ WARNING: this action assumes (and places) this project is under po4a
+ (translation) management. It will remove the sub-directories (if they exist):
+ #{language.possible_translations.inspect}
+
+ #{language.translation_languages_selected_that_are_available.inspect}
+ & file: #{filename.po4a_cfg}
+ in the current directory:
+ #{Dir.pwd}
+ Note: these sub-directories & the config file #{filename.po4a_cfg}
+ should be auto-generated from pot and po files if this project translation
+ is under po4a management.
+ This query is to give you the chance to make sure you know what you are doing.
+#{warn_and_proceed?}
+ WOK
+ when :rebuild
+ selections=:strict
+ <<-WOK
+ #{project_details.setup_project}
+ "--#{selection}" selected - #{selection} #{project_details.name}
+ WARNING: this action assumes (and places) this project is under po4a
+ (translation) management. It will destroy/clobber and then create again the
+ sub-directories:
+ #{language.translation_languages_selected_that_are_available.inspect}
+ populating them with translation files created from the pot and po files
+ found under the corresponding language sub-directories in (#{dir.pot}/
+ & #{dir.po}/).
+ It will also generate the file: #{filename.po4a_cfg}
+ These actions will be taken in the current directory:
+ #{Dir.pwd}
+ This query is to give you the chance to make sure you know what you are doing.
+#{warn_and_proceed?}
+ WOK
+ else
+ selections=:strict
+ <<-WOK
+ #{project_details.setup_project}
+ Default action selected - "#{selection} #{project_details.name}"
+#{warn_and_proceed?}
+ WOK
+ end
+ else
+ selections=:strict
+ <<-WOK
+ #{project_details.setup_project}
+ Default action selected - "install and to setup #{project_details.name}"
+#{warn_and_proceed?}
+ WOK
+ end
+ exit unless query.answer?(ans)
+ end
+ def project_help
+ puts <<-WOK
+#{project_details.name}
+#{project_details.setup_project}
+
+This setup file is primarily to assist with having sisu markup files under po4a
+translation management. It assumes that the source language files are placed
+under the sub-directory identifying the source language set, which is currently
+#{language.source_language_selected}
+The files there are used to make the source translation file in the directory #{dir.pot}/
+Which is then used to create files for translation under the directory #{dir.po}/
+in sub-directories bearing the translation languages ISO code.
+
+The current language translation selection is: #{translation_languages_selected_str}
+The languages selected are located in the file: #{filename.languages_src_tgt}
+
+sisu available language list: #{sisu_languages_available_str}
+
+ WOK
+ end
+ self
+ end
+ def generate
+ def readme
+ system(%{ruby ../../../../../bin/sisu6 --txt -v --no-manifest --dump='../../../../../..' en/README.ssm})
+ end
+ def manpage
+ system(%{ruby ../../../../../bin/sisu6 --manpage -v --no-manifest --dump='../../../../../../man/man1' en/sisu.ssm})
+ end
+ self
+ end
+ def filename
+ def languages_src_tgt
+ #'translation_languages'
+ 'languages_source_and_targets'
+ end
+ def po4a_cfg
+ 'po4a.cfg'
+ end
+ self
+ end
+ def dir
+ def pwd
+ Dir.pwd
+ end
+ def po4a_
+ 'po4a/' # ''
+ end
+ def pot
+ po4a_ + 'pot'
+ end
+ def po
+ po4a_ + 'po'
+ end
+ self
+ end
+ def dir_mk(dir)
+ FileUtils::mkdir_p(dir) unless FileTest.directory?(dir)
+ end
+ def po4a_flags
+ def debug
+ '-d -v'
+ end
+ def normal
+ ''
+ end
+ def quiet
+ '-q'
+ end
+ self
+ end
+ def languages_from_file
+ def language_source
+ if @@source.is_a?(String) \
+ and @@source =~ /w{2,4}/
+ else languages_extract_from_file
+ end
+ @@source
+ end
+ def language_targets
+ if @@targets.is_a?(Array) \
+ and @@targets.length > 0
+ else languages_extract_from_file
+ end
+ @@targets
+ end
+ def languages_extract_from_file
+ if (@@source.is_a?(String) \
+ and @@source =~/\w{2,4}/) \
+ and (@@targets.is_a?(Array) \
+ and @@targets.length > 0)
+ else
+ if FileTest.file?(filename.languages_src_tgt)
+ puts 'file: "' + filename.languages_src_tgt + '" found and used (unless overridden)'
+ langs=IO.read(filename.languages_src_tgt, mode: 'r:utf-8').scan(/source:\s+\w+|target:\s+\w.+/)
+ langs.each do |sel|
+ case sel
+ when /source:/
+ source=sel.split(/source:\s*|\s+/).join
+ source=(source =~/\w{2,4}/) ? source : nil
+ @@source=unless @@source.is_a?(String) \
+ and @@source =~/\w{2,4}/
+ source
+ else @@source
+ end
+ when /target:/
+ @@targets=unless @@targets.is_a?(Array)
+ sel.split(/targets?:\s*|\s+/) - ['']
+ else @@targets
+ end
+ end
+ end
+ else
+ puts %{(create) missing instruction file: "#{filename.languages_src_tgt}"\n contents e.g.:\n source: en\n target: de fr es ja ru zh\n no po target languages found}
+ exit
+ end
+ end
+ end
+ self
+ end
+ def language
+ def source_language_selected(src=nil)
+ @@source=if not @@source.nil? \
+ and @@source.is_a?(String) \
+ and @@source =~/\w{2,4}/
+ @@source
+ elsif (src \
+ && src.is_a?(String) \
+ && src.length > 1)
+ src
+ else
+ src=languages_from_file.language_source
+ end
+ end
+ def translation_languages_selected(targets=nil) #translation_languages
+ @@targets=if not @@targets.nil? \
+ and @@targets.is_a?(Array) \
+ and @@targets.length > 0
+ @@targets
+ elsif (targets \
+ && targets.is_a?(Array) \
+ && targets.length > 0)
+ targets
+ else
+ targets=languages_from_file.language_targets
+ end
+ end
+ def source_language_available
+ [source_language_selected] & sisu_languages_available
+ end
+ def translation_languages_selected_that_are_available
+ translation_languages_selected & sisu_languages_available
+ end
+ def info_on_selection
+ if translation_languages_selected != translation_languages_selected_that_are_available
+ <<-WOK
+WARNING: language selections mismatch
+
+The current language translation selection appears to be: #{translation_languages_selected_str}
+Of which the following are valid (available) selections: #{translation_languages_selected_that_are_available_str}
+
+sisu available language list: #{sisu_languages_available_str}
+
+the following will be used: #{translation_languages_selected_that_are_available_str}
+The languages selected are located in the file: #{filename.languages_src_tgt}
+ WOK
+ else
+ <<-WOK
+The current language translation selection is: #{translation_languages_selected_str}
+The languages selected are located in the file: #{filename.languages_src_tgt}
+
+sisu available language list: #{sisu_languages_available_str}
+ WOK
+ end
+ end
+ def sisu_languages_available
+ $SiSU_Language_Codes.language_list.codes
+ end
+ def possible_translations
+ sisu_languages_available - [source_language_selected]
+ end
+ def translation_languages_selected_str
+ language.translation_languages_selected.join(' ')
+ end
+ def source_language_available_str
+ source_language_available.join
+ end
+ def translation_languages_selected_that_are_available_str
+ language.translation_languages_selected_that_are_available.join(' ')
+ end
+ def sisu_languages_available_str
+ language.sisu_languages_available.join(' ')
+ end
+ def posible_translations_str
+ language.posible_translations.join(' ')
+ end
+ self
+ end
+ def files_src
+ def ssm
+ Dir.glob("#{language.source_language_selected}/*.ssm").sort
+ end
+ def sst
+ Dir.glob("#{language.source_language_selected}/*.sst").sort
+ end
+ def ssi
+ Dir.glob("#{language.source_language_selected}/*.ssi").sort
+ end
+ def all
+ Dir.glob("#{language.source_language_selected}/*{.ssm,.sst,.ssi}").sort
+ end
+ self
+ end
+ def po4a_cfg_file
+ File.open("#{Dir.pwd}/#{filename.po4a_cfg}",'w')
+ end
+ def po4a_create
+ def configure #po4a_cfg
+ po4a_cfg_arr=[]
+ po4a_cfg_arr \
+ << "[po4a_langs] #{language.translation_languages_selected_that_are_available_str}"
+ po4a_cfg_arr \
+ << "[po4a_paths] #{dir.pot}/$master.pot $lang:#{dir.po}/$lang/$master.po"
+ files_src.ssm.each do |file_src|
+ file_src_fn=file_src.gsub(/#{language.source_language_selected}\//,'')
+ po4a_cfg_arr \
+ << "[type: text] #{file_src} $lang:$lang/#{file_src_fn}"
+ end
+ files_src.sst.each do |file_src|
+ file_src_fn=file_src.gsub(/#{language.source_language_selected}\//,'')
+ po4a_cfg_arr \
+ << "[type: text] #{file_src} $lang:$lang/#{file_src_fn}"
+ end
+ files_src.ssi.each do |file_src|
+ file_src_fn=file_src.gsub(/#{language.source_language_selected}\//,'')
+ po4a_cfg_arr \
+ << "[type: text] #{file_src} $lang:$lang/#{file_src_fn}"
+ end
+ file=po4a_cfg_file
+ po4a_cfg_arr.each do |txt|
+ puts txt
+ file << txt << "\n"
+ end
+ file.close
+ cmd='po4a --keep 0 ' \
+ + po4a_flags.normal + ' ' \
+ + filename.po4a_cfg
+ #cmd='po4a --keep 0 --no-backups --package-name ' \
+ ,#+ 'sisu-manual' + ' ' \
+ ,#+ po4a_flags.normal + ' ' \
+ ,#+ filename.po4a_cfg
+ system(cmd); puts cmd
+ end
+ self
+ end
+ def project
+ def make
+ dir_mk(dir.pot)
+ language.translation_languages_selected_that_are_available.each do |lang_dir|
+ dir_lang="#{Dir.pwd}/#{dir.po}/#{lang_dir}"
+ dir_mk(dir_lang)
+ end
+ po4a_create.configure
+ end
+ def clean
+ #rm -f po/*/*.po~
+ #rm -rf ../build
+ FileUtils.rm_f Dir.glob("./#{dir.po}/*/*.po~")
+ end
+ def distclean
+ #rm -f po4a.cfg
+ #rm -rf $(LANGUAGES)
+ FileUtils::rm_f(filename.po4a_cfg)
+ FileUtils::rm_r(language.possible_translations,:force => true)
+ end
+ self
+ end
+end
+__END__
+#+END_SRC
+
+* Rake & Rant
+** Rake & Rant
+
+#+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: <https://sisudoc.org>
+
+ Copyright (C) 2007 Ralph Amissah
+
+ - License: LGPL - GNU Lesser General Public License
+ [same license as Rant provided within the Rant package]
+
+ - Ralph Amissah <ralph.amissah@gmail.com>
+
+ Rake is a Ruby build program by Jim Weirich
+ - Rake may be downloaded and installed from:
+ <https://rake.rubyforge.org/>
+
+ Rant is a Ruby build program by Stefan Lang
+ - Rant may be downloaded and installed from:
+ <https://make.rubyforge.org/>
+
+ Notes on use:
+ [if rake is preferred and installed]
+ rake -T
+ [if rant is preferred and installed]
+ rant -T
+
+ SiSU can also be Setup/Installation using:
+ * Minero Aoki's setup.rb, provided along with SiSU, or
+
+=end
+#%% produce a makefile suitable for the target platform
+#require 'mkmf'
+#create_makefile("sisu")
+#% manual settings, edit/update as required (note current default settings are obtained from sisu version yml file)
+require 'find'
+require 'fileutils'
+#require 'ftools'
+require 'rbconfig.rb'
+require 'yaml'
+include FileUtils
+require_relative 'sisu_version' # sisu_version.rb
+ include SiSUversion
+require_relative 'rbuild_libs' # rbuild_libs.rb
+ include Project_details
+ include Utils
+ include Version_info
+ include Gemspecs
+ include GitExtractTaggedVersionBuild
+require_relative 'rbuild_help' # rbuild_help.rb
+ include Help
+#% tasks
+desc "show rake/rant tasks for sisu install, and sisu gem (create spec, build &) install"
+task :default =>
+ [:note_sources,:tasks,:note_installation] #[:default_notice,:setup_base]
+desc "Setup/Install #{Project_details.name}"
+task :setup_project=>
+ [:setup_bin_,:setup_lib_,:setup_conf_,:setup_share_,:setup_data_,:setup_man_,:setup_vim_,:src_note]
+task :project=> \
+ [:setup_project]
+desc "Setup/Install #{Project_details.name}"
+task :setup=>
+ [:setup_bin_, :setup_lib_,:setup_conf_,:setup_share_,:setup_data_] #, :help]
+desc "Setup/Install #{Project_details.name}: bin, lib and conf (no data)"
+task :setup_base=>
+ [:setup_bin_,:setup_lib_,:setup_conf_,:setup_share_,:setup_man_,:setup_vim_,:note_sources]
+task :base=>
+ [:setup_base]
+desc "Setup/Install #{Project_details.name}: bin, lib, conf & data"
+task :setup_with_data=>
+ [:setup_base,:setup_data]
+desc "check package version"
+task :sisuversion =>
+ [:sisu_version]
+task :version =>
+ [:sisu_version]
+#desc "set package version"
+task :sisuversionset =>
+ [:sisu_version_set,:changelog_headers]
+desc "check gemspec info"
+task :gem_spec =>
+ [:gemspec_info]
+desc "create sisu v_stable gemspec"
+task :gem_create_spec_stable =>
+ [:gemspecs_stable_create_default_version]
+task :gem5cs =>
+ [:gem_create_spec_stable]
+task :gem5createspecs =>
+ [:gemspecs_stable_create_default_version]
+desc "create gemspec"
+task :gem_create_spec =>
+ [:gemspecs_create_default_version]
+task :gem_create =>
+ [:gemspecs_create_default_version]
+task :gemc =>
+ [:gemspecs_create_default_version]
+#---
+desc "build gem"
+task :gem_build =>
+ [:gem_build_]
+task :gemb =>
+ [:gem_build]
+task :gembuild =>
+ [:gem_build]
+desc "build sisu v_stable gem"
+task :gem_build_stable =>
+ [:gem_stable_build]
+task :gem5b =>
+ [:gem_build_stable]
+task :gem5build =>
+ [:gem_build_stable]
+#---
+desc "create, build & install sisu v_stable gem"
+ task :gem_create_build_install_stable =>
+ [:gemspecs_stable_create_default_version,:gem_stable_build,:gem_stable_install]
+task :gem5cbi =>
+ [:gem_create_build_install_stable]
+desc "create, build & install sisu gem"
+task :gem_create_build_install =>
+ [:gemspecs_create_default_version,:gem_build_,:gem_install_]
+task :gemcbi =>
+ [:gem_create_build_install]
+#---
+desc "install gem"
+task :gem_install =>
+ [:gem_install_]
+task :gemi =>
+ [:gem_install]
+task :geminstall =>
+ [:gem_install]
+desc "build & install sisu v_stable gem"
+task :gem_build_install_stable =>
+ [:gem_stable_build,:gem_install_]
+task :gem5bi =>
+ [:gem_build_install_stable]
+desc "build & install gem"
+task :gem_build_install =>
+ [:gem_build,:gem_install_]
+task :gembi =>
+ [:gem_build_install]
+#-- manually set next version
+#desc "create sisu v_stable gemspec, manually set next version"
+task :gem5csn =>
+ [:gemspecs_stable_create_next_version]
+#desc "create gemspec, manually set next version"
+task :gemcsn =>
+ [:gemspecs_create_next_version]
+task :gemcn =>
+ [:gemspecs_create_next_version]
+#desc "build gem, manually set next version"
+task :gembn =>
+ [:gem_build_next_version]
+#desc "build sisu v_stable gem, manually set next version"
+task :gem5bn =>
+ [:gem_stable_build_next_version]
+#desc "install gem, manually set next version"
+task :gemin =>
+ [:gem_install_next_version]
+#desc "build & install sisu v_stable gem, manually set next version"
+task :gem5bin =>
+ [:gem_stable_build_next_version,:gem_install_next_version]
+#desc "build & install gem, manually set next version"
+task :gembin =>
+ [:gem_build_next_version,:gem_install_next_version]
+#desc "create, build & install sisu v_stable gem, manually set next version"
+task :gem5cbin =>
+ [:gemspecs_stable_create_next_version,:gem_stable_build_next_version,:gem_stable_install_next_version]
+#desc "create, build & install sisu gem, manually set next version"
+task :gemcbin =>
+ [:gemspecs_create_next_version,:gem_build_next_version,:gem_install_next_version]
+#---
+#desc "check changelog headers"
+task :changelogheaders =>
+ [:changelog_headers]
+task :dev =>
+ [:note_developer]
+task :developer_note =>
+ [:note_developer]
+if File.directory?('bin')
+ desc "Setup #{Project_details.name} bin only, synonym :bin"
+ task :setup_bin =>
+ [:setup_bin_]
+ task :bin =>
+ [:setup_bin]
+end
+if File.directory?('lib')
+ desc "Setup #{Project_details.name} lib only, synonym :lib"
+ task :setup_lib =>
+ [:setup_lib_]
+ task :lib =>
+ [:setup_lib]
+end
+if File.directory?('conf')
+ desc "Setup #{Project_details.name} conf only, synonyms :conf & :etc"
+ task :setup_conf =>
+ [:setup_conf_]
+ task :conf =>
+ [:setup_conf]
+ task :setup_etc =>
+ [:setup_conf]
+ task :etc =>
+ [:setup_conf]
+end
+if File.directory?('data')
+ desc "Setup #{Project_details.name} data only, synonyms :data & :examples"
+ task :setup_data =>
+ [:setup_data_]
+ task :data =>
+ [:setup_data]
+ task :setup_examples =>
+ [:setup_data]
+ task :examples =>
+ [:setup_data]
+end
+if File.directory?('data/sisu')
+ #desc "Setup #{Project_details.name} shared data only (odf & shared images)"
+ task :setup_share =>
+ [:setup_share_]
+ task :share =>
+ [:setup_share]
+end
+if File.directory?('man')
+ desc "Setup #{Project_details.name} man pages only, synonyms :man"
+ task :setup_man =>
+ [:setup_man_]
+ task :man =>
+ [:setup_man]
+end
+if File.directory?('data/vim')
+ desc "Setup #{Project_details.name} vim config files only, synonyms :vim"
+ task :setup_vim =>
+ [:setup_vim_]
+ task :vim =>
+ [:setup_vim]
+end
+desc "Remove #{Project_details.name} (all versions)"
+task :remove_package =>
+ [:remove_bin, :remove_lib, :remove_conf]
+if File.directory?('bin')
+ #desc "Remove #{Project_details.name} bin only"
+ task :remove_bin =>
+ [:remove_bin]
+end
+if File.directory?('lib')
+ #desc "Remove #{Project_details.name} lib only"
+ task :remove_lib =>
+ [:remove_lib]
+end
+if File.directory?('conf')
+ #desc "Remove #{Project_details.name} conf only"
+ task :remove_conf =>
+ [:remove_conf]
+end
+desc "Re-setup #{Project_details.name}, synonym :reinstall"
+task :resetup =>
+ [:remove, :setup]
+task :reinstall =>
+ [:remove, :setup]
+#desc "Re-setup #{Project_details.name}: bin, lib, conf (ignore data), synonym :reinstall"
+task :resetup_base =>
+ [:remove, :setup_base_]
+task :reinstall_base =>
+ [:remove, :setup_base_]
+if File.directory?('bin')
+ #desc "Re-setup #{Project_details.name} bin, synonym :reinstall"
+ task :resetup_bin =>
+ [:remove_bin, :setup_bin_]
+ task :reinstall_bin =>
+ [:remove_bin, :setup_bin_]
+end
+if File.directory?('lib')
+ #desc "Re-setup #{Project_details.name} lib, synonym :reinstall_lib"
+ task :resetup_lib =>
+ [:remove_lib, :setup_lib_]
+ task :reinstall_lib =>
+ [:remove_lib, :setup_lib_]
+end
+if File.directory?('conf')
+ #desc "Re-setup #{Project_details.name} conf, synonyms :reinstall_conf & :resetup_etc"
+ task :resetup_conf =>
+ [:remove_conf, :setup_conf_]
+ task :reinstall_conf =>
+ [:remove_conf, :setup_conf_]
+ task :resetup_etc =>
+ [:remove_conf, :setup_conf_]
+ task :reinstall_etc =>
+ [:remove_conf, :setup_conf_]
+end
+if File.directory?('data/sisu')
+ #desc "Re-setup #{Project_details.name} shared data, (odf & images)"
+ task :resetup_share =>
+ [:remove_share, :setup_share_]
+ task :reinstall_share =>
+ [:remove_share, :setup_share_]
+end
+if File.directory?('man')
+ #desc "Re-setup #{Project_details.name} man, synonym :reinstall_man"
+ task :resetup_man =>
+ [:remove_man, :setup_man_]
+ task :reinstall_man =>
+ [:remove_man, :setup_man_]
+end
+desc 'Setup Note'
+task :setup_note =>
+ [:help]
+desc "System information used by #{Project_details.name}"
+task :system =>
+ [:system_info,:project_help,:note_sources]
+desc "show all system info available - parameters found"
+task :system_param =>
+ [:system_param_]
+desc "Gem environment information used ruby gems for #{Project_details.name}"
+task :gem_env =>
+ [:gem_env_]
+desc 'Help'
+task :help =>
+ [:project_help,:system_info,:tasks]
+#desc "Setup/Install #{Project_details.name} (uses filelist)"
+task :install =>
+ [:default_notice,:project]
+task :install_bin =>
+ [:setup_bin_]
+#desc "search for a version tag e.g. 'tag[5.6.0]'"
+task :tag, [:tag] do |t, args|
+ args.with_defaults(:tag => Version_info::Next.setting_stable[:version])
+ puts "Check for Version Tag: #{args.tag}"
+ print "Version Tag: "
+ GitExtractTaggedVersionBuild::git_tagged_versions(args)
+end
+#desc "build and install a specific git tagged version of sisu, e.g. 'build[5.6.0]'"
+task :build, [:tag, :branch] => :done do |t, args|
+ args.with_defaults(:tag => '5.6.0', :branch => 'stable')
+ puts "Version Tag: #{args.tag}"
+ puts "Branch: #{args.branch}"
+ GitExtractTaggedVersionBuild::git_tagged_versions(args.tag)
+ ans= <<-WOK
+Gem Install SiSU Version
+ WOK
+ resp=Utils.answer?(ans)
+ exit unless resp
+ GitExtractTaggedVersionBuild::git_checkout_and_build_version(args)
+end
+task :done do
+ puts 'done'
+end
+ #%% setup/install tasks
+task :rant_independence do #notice
+ resp=''
+ while resp.length < 4
+ resp='sisu-install' #default name install
+ print %{#{Project_details.rake_rant}
+ Create a rant dependency independent file
+ provide filename default name is "install"
+ [Warning, will overwrite file of name provided
+ provide name or "quit" to exit]: }
+ exit if resp =~/^(?:n|quit|exit)$/
+ end
+ remove='y' #remove='n'
+ if remove =~/y/
+ system("rant-import --force --auto #{resp};
+ chmod 755 #{resp}
+ ")
+ else #puts "#{resp} not replaced"
+ end
+end
+
+task :default_notice do #notice
+ Utils.default_notice
+end
+task :default2 do #secondary
+ setup_find_cp_r('bin',Project_details.dir.bin) \
+ if File.directory?('bin')
+ setup_find_cp_r('lib',Project_details.dir.lib) \
+ if File.directory?('lib')
+ setup_find_cp_r('conf',Project_details.dir.conf) \
+ if File.directory?('conf')
+ setup_find_cp_r('data/sisu',Project_details.dir.share) \
+ if File.directory?('data/sisu') #
+ setup_find_cp_r('data',Project_details.dir.data) \
+ if File.directory?('data')
+ setup_find_cp_r('data/vim',"#{Project_details.dir.data}/vim") \
+ if File.directory?('data/vim')
+ setup_find_cp_r('man',Project_details.dir.man) \
+ if File.directory?('man')
+end
+task :setup_bin_ do
+ exclude_files=['sisugem']
+ Install.setup_find_create('bin',Project_details.dir.bin,exclude_files) \
+ if File.directory?('bin')
+end
+task :setup_lib_ do
+ Install.setup_find_create('lib',Project_details.dir.lib) \
+ if File.directory?('lib')
+end
+task :setup_conf_ do
+ Install.setup_find_create('conf',Project_details.dir.conf) \
+ if File.directory?('conf')
+end
+task :setup_share_ do
+ Install.setup_find_create('data/sisu',Project_details.dir.share) \
+ if File.directory?('data/sisu')
+end
+task :setup_data_ do
+ Install.setup_find_create('data',Project_details.dir.data) \
+ if File.directory?('data')
+end
+task :setup_man_ do
+ Install.setup_find_create('man',Project_details.dir.man) \
+ if File.directory?('man')
+ Install.setup_find_create('man.deb/man',Project_details.dir.man) \
+ if File.directory?('man.deb/man')
+end
+task :setup_vim_ do
+ Install.setup_find_create('data/vim',Project_details.dir.vim) \
+ if File.directory?('data/vim')
+end
+task :gemspec_info do
+ Gemspecs.info_stable
+end
+task :gemspecs_stable_create_default_version do
+ Gemspecs::Current.create_stable
+end
+task :gemspecs_create_default_version do
+ Gemspecs::Current.create_stable
+end
+task :gemspecs_stable_create_next_version do
+ Gemspecs::Next.create_stable
+end
+task :gemspecs_create_next_version do
+ Gemspecs::Next.create_stable
+end
+task :gem_stable_build do
+ Gemspecs::Current.build_stable
+end
+task :gem_build_ do
+ Gemspecs::Current.build_stable
+end
+task :gem_stable_build_next_version do
+ Gemspecs::Next.build_stable
+end
+task :gem_build_next_version do
+ Gemspecs::Next.build_stable
+end
+task :gem_stable_install do
+ Gemspecs::Current.install_stable
+end
+task :gem_install_ do
+ Gemspecs::Current.install_stable
+end
+task :gem_stable_install_next_version do
+ Gemspecs::Next.install_stable
+end
+task :gem_install_next_version do
+ Gemspecs::Next.install_stable
+end
+task :changelog_headers do
+ puts '---'
+ puts Version_info::Update.changelog_header_stable
+end
+task :sisu_version do
+ puts Version_info::Next.setting_stable
+ puts '---'
+ puts Version_info::Current.setting_stable[:project]
+ puts Version_info::Current.setting_stable[:version]
+ puts Version_info::Current.setting_stable[:date]
+ puts Version_info::Current.setting_stable[:date_stamp]
+end
+task :sisu_version_set do
+ Version_info::Update.update_stable
+end
+ #%% post install
+ #%% clobber/remove tasks
+task :remove_bin do
+ rm_r "#{Project_details.dir.bin}/#{Project_details.dir.proj}" \
+ if FileTest.file?("#{Project_details.dir.bin}/#{Project_details.dir.proj}")
+end
+task :remove_lib do
+ rm_r "#{Project_details.dir.lib}/#{Project_details.dir.proj}" \
+ if FileTest.directory?("#{Project_details.dir.lib}/#{Project_details.dir.proj}")
+end
+task :remove_conf do
+ rm_r "#{Project_details.dir.conf}/#{Project_details.dir.proj}" \
+ if FileTest.directory?("#{Project_details.dir.conf}/#{Project_details.dir.proj}")
+end
+task :remove_man do
+ rm_r "#{Project_details.dir.man}/**/#{Project_details.dir.proj}" \
+ if FileTest.directory?("#{Project_details.dir.man}/man1/#{Project_details.dir.proj}")
+end
+task :remove_version do
+ rm_r "#{Project_details.dir.bin}/#{Project_details.dir.proj}" \
+ if FileTest.file?("#{Project_details.dir.bin}/#{Project_details.dir.proj}")
+ rm_r "#{Project_details.dir.lib}/#{Project_details.dir.proj}/#{Project_details.version}" \
+ if FileTest.directory?("#{Project_details.dir.lib}/#{Project_details.dir.proj}/#{Project_details.version}")
+ rm_r "#{Project_details.dir.conf}/#{Project_details.dir.proj} \
+ if FileTest.directory?("#{Project_details.dir.conf}/#{Project_details.dir.proj}")
+end
+task :remove_package do
+ rm_r "#{Project_details.dir.bin}/#{Project_details.dir.proj}" \
+ if FileTest.file?("#{Project_details.dir.bin}/#{Project_details.dir.proj}")
+ rm_r "#{Project_details.dir.lib}/#{Project_details.dir.proj}" \
+ if FileTest.directory?("#{Project_details.dir.lib}/#{Project_details.dir.proj}")
+ rm_r "#{Project_details.dir.conf}/#{Project_details.dir.proj}" \
+ if FileTest.directory?("#{Project_details.dir.conf}/#{Project_details.dir.proj}")
+end
+task :note_sources do
+ puts <<-WOK
+
+ SiSU project:
+ <https://sisudoc.org>
+ sisu source code is available at:
+ <https://git.sisudoc.org>
+ <https://git.sisudoc.org/projects/sisu>
+ sisu markup samples are provided/packaged separately as sisu-markup-samples:
+ <https://git.sisudoc.org/projects/sisu-markup>
+ 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 <<WOK
+
+#{Project_details.name}
+ #{Project_details.rake_rant}
+ #{Project_details.platform_notice}
+
+Commands quick start list
+ #{Project_details.name} Rake/Rant Help: (Rakefile or Rantfile)
+ rake (rake -T or rant -T) # a task list, (generated by Rake or Rant) for more complete and up to date help
+
+ Quick start install and remove project #{Project_details.name}, as root:
+ rake setup # install #{Project_details.name}
+ rake resetup # reinstall #{Project_details.name}
+ rake remove_package # clobber/remove #{Project_details.name}, all versions
+ alternatively to install as a gem:
+ rake gem_create_build_install # create gemspec; build gem, &; install gem, for #{Project_details.name}
+
+ NOTE: these install options DO NOT setup #{Project_details.name} dependencies for:
+ LaTeX(XeTeX) pdf output; or
+ databases (postgresql or sqlite3) for #{Project_details.name} search
+ should you wish to produce outputs that depend on them
+ (on Debian for example this is the work of the debian installer)
+
+WOK
+ end
+ def self.tasks(make='rake')
+ begin
+ system("#{make} -T")
+ rescue
+ puts 'is either rake or rant installed?'
+ end
+ end
+end
+#+END_SRC
+
+* 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:
+- <https://www.sisudoc.org/>
+
+INSTALL OR RUN WITHOUT INSTALLATION
+***********************************
+
+SOURCE TREE
+-----------
+
+RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING)
+..........................................................
+
+Download & unpack the latest source tarball
+
+or
+
+Git clone the latest source, to clone the latest source without the repo
+history:
+
+git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream
+
+Provided you have *Ruby*, *SiSU* can be run without installation straight from
+the source package directory tree. Run ruby against the full path to bin/sisu
+(in the unzipped source package directory tree)
+
+Note however, that additional external package dependencies, such as texlive
+(for pdfs), sqlite3 or postgresql (for search) should you desire to use them
+are not taken care of for you.
+
+GEM INSTALL
+...........
+
+Gem install, you need to:
+
+(i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install
+the gem
+
+
+----------------------------------------
+
+GEM INSTALL WITH QI (QUICK INSTALL) SCRIPT
+..........................................
+
+(This requires that ruby -thor is installed).
+
+qi (quick install) can go through the steps required to install the gem:
+
+ qi gem --create --build --install --stable
+
+or
+
+ qi gem --create --build --install --unstable
+
+
+----------------------------------------
+
+GEM INSTALL WITH RAKE
+.....................
+
+Provided you have ruby & rake, this can be done with the single command:
+
+ rake gem_create_build_install # (to build and install, alias gemcbi)
+
+for individual steps (create, build, install) see rake options, rake -T to
+specify sisu version for sisu installed via gem
+
+For a list of alternative actions you may type:
+
+ rake help
+
+ rake -T
+
+Rake: <https://rake.rubyforge.org/> <https://rubyforge.org/frs/?group_id=50>
+
+
+----------------------------------------
+
+MISC GEM
+........
+
+gem search sisu
+
+ sisu _7.0.0_ --version
+
+ sisu _7.0.0_ --version
+
+to uninstall sisu installed via gem
+
+ sudo gem uninstall --verbose sisu
+
+DIRECT INSTALLATION WITH QI (QUICK INSTALL) SCRIPT
+..................................................
+
+(This requires that ruby -thor is installed).
+
+Root will be requested as required:
+
+ qi setup --bin --lib --conf --data --share --man
+
+or
+
+ qi setup --all
+
+You may wish to do a dryrun to see where files would be installed without
+copying them, to do so add the flag --dryrun
+
+INSTALLATION WITH SETUP.RB
+..........................
+
+It should also be possible to install sisu using setup.rb
+
+this is a three step process, in the root directory of the unpacked *SiSU* as
+root type:
+
+ruby setup.rb config
+ruby setup.rb setup
+#[as root:]
+ruby setup.rb install
+
+further information:
+<https://i.loveruby.net/en/projects/setup/>
+<https://i.loveruby.net/en/projects/setup/doc/usage.html>
+
+ ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install
+
+UNIX/LINUX DISTRIBUTION
+-----------------------
+
+A distribution install should take care of the dependencies of sisu for
+producing various outputs.
+
+DEBIAN
+......
+
+*SiSU* is available off the *Debian* archives. It should necessary only to run
+as root, Using apt-get:
+
+ apt-get update
+
+ apt get install sisu-complete
+
+(all sisu dependencies should be taken care of)
+
+If there are newer versions of *SiSU* upstream, they will be available by
+adding the following to your sources list /etc/apt/sources.list
+
+#/etc/apt/sources.list
+
+deb 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:
+<https://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>]
+[^1] install it using apt-get, aptitude or alternative *Debian* install tools.
+
+DEPENDENCIES
+------------
+
+Here is a list of sisu' s current dependencies,[^2] which depend on such
+factors as whether you want to generate pdf, whether you will be using *SiSU*
+with or without a database, ...). sisu_markup-samples may also be of interest.
+
+Package: sisu
+Depends: ruby | ruby-interpreter, openssl, rsync, unzip, zip
+Recommends: sisu-pdf, sisu-sqlite, sisu-postgresql, imagemagick |
+graphicsmagick, keychain, openssh-client | lsh-client, po4a, qrencode, rake,
+ruby-rmagick, tidy, tree, vim-addon-manager
+Suggests: lv, calibre, pinfo, poedit, texinfo, trang
+
+Package: sisu-complete
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sisu-pdf (=
+${source:Version}), sisu-postgresql (= ${source:Version}), sisu-sqlite (=
+${source:Version})
+Description-en: installs all SiSU related packages
+
+Package: sisu-pdf
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}),
+texlive-latex-base, texlive-fonts-recommended, texlive-generic-recommended,
+texlive-latex-recommended, texlive-latex-extra, texlive-math-extra,
+texlive-xetex, fonts-liberation, lmodern, latex-cjk-all, texlive-lang-cjk
+Suggests: evince | pdf-viewer
+
+Package: sisu-postgresql
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), postgresql,
+ruby-dbd-pg, ruby-dbi, ruby-fcgi
+Suggests: postgresql-contrib
+
+Package: sisu-sqlite
+Depends: ruby | ruby-interpreter, sisu (= ${source:Version}), sqlite3,
+ruby-sqlite3, ruby-dbd-sqlite3, ruby-dbi, ruby-fcgi
+
+Package: sisu-markup-samples
+Depends: sisu
+
+COMMANDS
+********
+
+COMMANDS SUMMARY
+----------------
+
+DESCRIPTION
+...........
+
+*SiSU* is a document publishing system, that from a simple single marked-up
+document, produces multiple output formats including: /plaintext/, /HTML/,
+/XHTML/, /XML/, /EPUB/, /ODT/ (/OpenDocument/ (/ODF/) text), /LaTeX/, /PDF/,
+info, and /SQL/ (/PostgreSQL/ and /SQLite/) , which share text object numbers
+("object citation numbering") and the same document structure information. For
+more see: <https://sisudoc.org> or <https://git.sisudoc.org>
+
+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 <https://git.sisudoc.org/sisu-markup> 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 <https://www.sisudoc.org/> 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: <https://www.sisudoc.org/>] markup
+
+A shortcut notation is available so the url link may also be provided
+automatically as a footnote
+
+*markup example:*
+
+about {~^ SiSU }https://url.org markup
+
+*resulting output:*
+
+about SiSU [link: <https://www.sisudoc.org/>] [^7] markup
+
+Internal document links to a tagged location, including an ocn
+
+*markup example:*
+
+about { text links }#link_text
+
+*resulting output:*
+
+about text links
+
+Shared document collection link
+
+*markup example:*
+
+about { SiSU book markup examples }:SiSU/examples.html
+
+*resulting output:*
+
+about *SiSU* book markup examples
+
+
+----------------------------------------
+
+LINKING IMAGES
+..............
+
+*markup example:*
+
+{ tux.png 64x80 }image
+
+% various url linked images
+[image: "a better way"]
+ [image: "Way Better - with Gnu/Linux, Debian and Ruby"]
+
+{~^ ruby_logo.png "Ruby" }https://www.ruby-lang.org/en/
+
+*resulting output:*
+
+tux.png 64x80 [link: local image]
+
+tux.png 64x80 "Gnu/Linux - a better way" [link: <https://www.sisudoc.org/>]
+
+GnuDebianLinuxRubyBetterWay.png 100x101 "Way Better - with Gnu/Linux, Debian
+and Ruby" [link: <https://www.sisudoc.org/>]
+
+ruby_logo.png 70x90 "Ruby" [link: <https://www.ruby-lang.org/en/>] [^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: <https://www.sisudoc.org/sisu/en/manifest/viral_spiral.david_bollier.manifest.html>]
+ document manifest [link: <https://www.sisudoc.org/sisu/en/manifest/viral_spiral.david_bollier.manifest.html>]
+ html, segmented text [link: <https://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier/viral_spiral.david_bollier.toc.html>]
+ html, scroll, document in one [link: <https://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier.html>]
+ epub [link: <https://www.sisudoc.org/sisu/en/epub/viral_spiral.david_bollier.epub>]
+ pdf, landscape [link: <https://www.sisudoc.org/sisu/en/pdf/viral_spiral.david_bollier.landscape.a4.pdf>]
+ pdf, portrait [link: <https://www.sisudoc.org/sisu/en/pdf/viral_spiral.david_bollier.landscape.a4.pdf>]
+ odf: odt, open document text [link: <https://www.sisudoc.org/sisu/en/odt/viral_spiral.david_bollier.odt>]
+ xhtml scroll [link: <https://www.sisudoc.org/sisu/en/xhtml/viral_spiral.david_bollier.xhtml>]
+ xml, sax [link: <https://www.sisudoc.org/sisu/en/xml_sax/viral_spiral.david_bollier.sax.xml>]
+ xml, dom [link: <https://www.sisudoc.org/sisu/en/xml_dom/viral_spiral.david_bollier.dom.xml>]
+ concordance [link: <https://www.sisudoc.org/sisu/en/html/viral_spiral.david_bollier/concordance.html>]
+ dcc, document content certificate (digests) [link: <https://www.sisudoc.org/sisu/en/digest/viral_spiral.david_bollier.hash_digest.txt>]
+ markup source text [link: <https://www.sisudoc.org/sisu/en/src/viral_spiral.david_bollier.sst>]
+ markup source (zipped) pod [link: <https://www.sisudoc.org/sisu/en/src/viral_spiral.david_bollier.sst.zip>]
+
+GROUPED TEXT / BLOCKED TEXT
+...........................
+
+There are two markup syntaxes for blocked text, using curly braces or using
+tics
+
+
+----------------------------------------
+
+BLOCKED TEXT CURLY BRACE SYNTAX
+...............................
+
+at the start of a line on its own use name of block type with an opening curly
+brace, follow with the content of the block, and close with a closing curly
+brace and the name of the block type, e.g.
+
+code{
+this is a code block
+
+}code
+
+poem{
+
+this here is a poem
+
+}poem
+
+
+----------------------------------------
+
+BLOCKED TEXT TIC SYNTAX
+.......................
+
+``` code
+this is a code block
+
+```
+
+``` poem
+
+this here is a poem
+
+```
+
+start a line with three backtics, a space followed by the name of the name of
+block type, follow with the content of the block, and close with three back
+ticks on a line of their own, e.g.
+
+
+----------------------------------------
+
+TABLES
+......
+
+Tables may be prepared in two either of two forms
+
+*markup example:*
+
+table{ c3; 40; 30; 30;
+
+This is a table
+this would become column two of row one
+column three of row one is here
+
+And here begins another row
+column two of row two
+column three of row two, and so on
+
+}table
+
+*resulting output:*
+
+This is a table┆this would become column two of row one┆column three of row one is here』And here begins another row┆column two of row two┆column three of row two, and so on』
+
+a second form may be easier to work with in cases where there is not much
+information in each column
+
+*markup example:*[^9]
+
+!_ Table 3.1: Contributors to Wikipedia, January 2001 - June 2005
+
+{table~h 24; 12; 12; 12; 12; 12; 12;}
+ |Jan. 2001|Jan. 2002|Jan. 2003|Jan. 2004|July 2004|June 2006
+Contributors* | 10| 472| 2,188| 9,653| 25,011| 48,721
+Active contributors** | 9| 212| 846| 3,228| 8,442| 16,945
+Very active contributors*** | 0| 31| 190| 692| 1,639| 3,016
+No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000
+No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000
+
+- Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month.
+
+*resulting output:*
+
+*Table 3.1: Contributors to Wikipedia, January 2001 - June 2005*
+
+┆Jan. 2001┆Jan. 2002┆Jan. 2003┆Jan. 2004┆July 2004┆June 2006』Contributors*┆10┆472┆2,188┆9,653┆25,011┆48,721』Active contributors**┆9┆212┆846┆3,228┆8,442┆16,945』Very active contributors***┆0┆31┆190┆692┆1,639┆3,016』No. of English language articles┆25┆16,000┆101,000┆190,000┆320,000┆630,000』No. of articles, all languages┆25┆19,000┆138,000┆490,000┆862,000┆1,600,000』
+
+- Contributed at least ten times; ** at least 5 times in last month; *** more
+than 100 times in last month.
+
+
+----------------------------------------
+
+POEM
+....
+
+*basic markup:*
+
+poem{
+
+ Your poem here
+
+}poem
+
+Each verse in a poem is given an object number.
+
+*markup example:*
+
+poem{
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+}poem
+
+*resulting output:*
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+
+----------------------------------------
+
+GROUP
+.....
+
+*basic markup:*
+
+group{
+
+ Your grouped text here
+
+}group
+
+A group is treated as an object and given a single object number.
+
+*markup example:*
+
+group{
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+}group
+
+*resulting output:*
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+
+----------------------------------------
+
+CODE
+....
+
+Code tags # code{ ... }code # (used as with other group tags described above)
+are used to escape regular sisu markup, and have been used extensively within
+this document to provide examples of *SiSU* markup. You cannot however use code
+tags to escape code tags. They are however used in the same way as group or
+poem tags.
+
+A code-block is treated as an object and given a single object number. [an
+option to number each line of code may be considered at some later time]
+
+*use of code tags instead of poem compared, resulting output:*
+
+ `Fury said to a
+ mouse, That he
+ met in the
+ house,
+ "Let us
+ both go to
+ law: I will
+ prosecute
+ YOU. --Come,
+ I'll take no
+ denial; We
+ must have a
+ trial: For
+ really this
+ morning I've
+ nothing
+ to do."
+ Said the
+ mouse to the
+ cur, "Such
+ a trial,
+ dear Sir,
+ With
+ no jury
+ or judge,
+ would be
+ wasting
+ our
+ breath."
+ "I'll be
+ judge, I'll
+ be jury,"
+ Said
+ cunning
+ old Fury:
+ "I'll
+ try the
+ whole
+ cause,
+ and
+ condemn
+ you
+ to
+ death."'
+
+From *SiSU* 2.7.7 on you can number codeblocks by placing a hash after the
+opening code tag # code{# # as demonstrated here:
+
+1 ┆ `Fury said to a
+2 ┆ mouse, That he
+3 ┆ met in the
+4 ┆ house,
+5 ┆ "Let us
+6 ┆ both go to
+7 ┆ law: I will
+8 ┆ prosecute
+9 ┆ YOU. --Come,
+10 ┆ I'll take no
+11 ┆ denial; We
+12 ┆ must have a
+13 ┆ trial: For
+14 ┆ really this
+15 ┆ morning I've
+16 ┆ nothing
+17 ┆ to do."
+18 ┆ Said the
+19 ┆ mouse to the
+20 ┆ cur, "Such
+21 ┆ a trial,
+22 ┆ dear Sir,
+23 ┆ With
+24 ┆ no jury
+25 ┆ or judge,
+26 ┆ would be
+27 ┆ wasting
+28 ┆ our
+29 ┆ breath."
+30 ┆ "I'll be
+31 ┆ judge, I'll
+32 ┆ be jury,"
+33 ┆ Said
+34 ┆ cunning
+35 ┆ old Fury:
+36 ┆ "I'll
+37 ┆ try the
+38 ┆ whole
+39 ┆ cause,
+40 ┆ and
+41 ┆ condemn
+42 ┆ you
+43 ┆ to
+44 ┆ death."'
+
+ADDITIONAL BREAKS - LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE-BREAKS
+.....................................................................
+
+
+----------------------------------------
+
+LINE-BREAKS
+...........
+
+To break a line within a "paragraph object", two backslashes \\
+with a space before and a space or newline after them
+may be used.
+
+To break a line within a "paragraph object",
+two backslashes \\ with a space before
+and a space or newline after them \\
+may be used.
+
+The html break br enclosed in angle brackets (though undocumented) is available
+in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being,
+but is depreciated).
+
+To draw a dividing line dividing paragraphs, see the section on page breaks.
+
+
+----------------------------------------
+
+PAGE BREAKS
+...........
+
+Page breaks are only relevant and honored in some output formats. A page break
+or a new page may be inserted manually using the following markup on a line on
+its own:
+
+page new =\= breaks the page, starts a new page.
+
+page break -\- breaks a column, starts a new column, if using columns, else
+breaks the page, starts a new page.
+
+page break line across page -..- draws a dividing line, dividing paragraphs
+
+page break:
+
+-\\-
+
+page (break) new:
+
+=\\=
+
+page (break) line across page (dividing paragraphs):
+
+-..-
+
+BIBLIOGRAPHY / REFERENCES
+.........................
+
+There are three ways to prepare a bibliography using sisu (which are mutually
+exclusive): (i) manually preparing and marking up as regular text in sisu a
+list of references, this is treated as a regular document segment (and placed
+before endnotes if any); (ii) preparing a bibliography, marking a heading level
+1~!biblio (note the exclamation mark) and preparing a bibliography using
+various metadata tags including for author: title: year: a list of which is
+provided below, or; (iii) as an assistance in preparing a bibliography, marking
+a heading level 1~!biblio and tagging citations within footnotes for inclusion,
+identifying citations and having a parser attempt to extract them and build a
+bibliography of the citations provided.
+
+For the heading/section sequence: endnotes, bibliography then book index to
+occur, the name biblio or bibliography must be given to the bibliography
+section, like so:
+
+1~!biblio
+
+
+----------------------------------------
+
+A MARKUP TAGGED METADATA BIBLIOGRAPHY SECTION
+.............................................
+
+Here instead of writing your full citations directly in footnotes, each time
+you have new material to cite, you add it to your bibliography section (if it
+has not been added yet) providing the information you need against an available
+list of tags (provided below).
+
+The required tags are au: ti: and year: [^10] an short quick example might be
+as follows:
+
+1~!biblio
+
+au: von Hippel, E.
+ti: Perspective: User Toolkits for Innovation
+lng: (language)
+jo: Journal of Product Innovation Management
+vo: 18
+ed: (editor)
+yr: 2001
+note:
+sn: Hippel, /{User Toolkits}/ (2001)
+id: vHippel_2001
+% form:
+
+au: Benkler, Yochai
+ti: The Wealth of Networks
+st: How Social Production Transforms Markets and Freedom
+lng: (language)
+pb: Harvard University Press
+edn: (edition)
+yr: 2006
+pl: U.S.
+url: 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]: <https://packages.qa.debian.org/s/sisu.html>
+
+ [2]: from the *Debian* control file
+
+ [*1]: square brackets
+
+ [*2]: square brackets
+
+ [+1]: square brackets
+
+ [3]: From sometime after SiSU 0.58 it should be possible to describe SiSU markup
+ using SiSU, which though not an original design goal is useful.
+
+ [4]: files should be prepared using /UTF-8/ character encoding
+
+ [5]: a footnote or endnote
+
+ [6]: self contained endnote marker & endnote in one
+
+ [*]: unnumbered asterisk footnote/endnote, insert multiple asterisks if required
+
+ [**]: another unnumbered asterisk footnote/endnote
+
+ [*3]: editors notes, numbered asterisk footnote/endnote series
+
+ [+2]: editors notes, numbered plus symbol footnote/endnote series
+
+ [7]: <https://www.sisudoc.org/>
+
+ [8]: <https://www.ruby-lang.org/en/>
+
+ [9]: Table from the Wealth of Networks by Yochai Benkler
+
+ <https://sisudoc.org/spine/en/html/the_wealth_of_networks.yochai_benkler/toc.html>
+
+ [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 <www.sisudoc.org> or
+ <git.sisudoc.org/> software for electronic texts, document collections,
+ books, digital libraries, and search, with "atomic search" and text positioning
+ system (shared text citation numbering: "ocn")
+ outputs include: plaintext, html, XHTML, XML, ODF (OpenDocument), EPUB, LaTeX,
+ PDF, SQL (PostgreSQL and SQLite)
+
+**** SiSU Short Description
+
+ SiSU is a comprehensive future-resilient electronic document management system.
+ Built-in search capabilities allow you to search across multiple documents and
+ highlight matches in an easy-to-follow format. Paragraph numbering system
+ allows you to cite your electronic documents in a consistent manner across
+ multiple file formats. Multiple format outputs allow you to display your
+ documents in plain text, PDF (portrait and horizontal), OpenDocument format,
+ HTML, or e-book reading format (EPUB). Word mapping allows you to easily create
+ word indexes for your documents. Future-resilient flexibility allows you to
+ quickly adapt your documents to newer output formats as needed. All these and
+ many other features are achieved with little or no additional work on your
+ documents - by marking up the documents with a super simplistic markup
+ language, leaving the SiSU engine to handle the heavy-lifting processing.
+
+ Potential users of SiSU include individual authors who want to publish their
+ books or articles electronically to reach a broad audience, web publishers who
+ want to provide multiple channels of access to their electronic documents, or
+ any organizations which centrally manage a medium or large set of electronic
+ documents, especially governmental organizations which may prefer to keep their
+ documents in easily accessible yet non-proprietary formats.
+
+ SiSU is an Open Source project initiated and led by Ralph Amissah
+ <ralph.amissah@gmail.com> and can be contacted via mailing list
+ <https://lists.sisudoc.org/listinfo/sisu> at <sisu@lists.sisudoc.org>. SiSU is
+ licensed under the GNU General Public License.
+
+***** notes
+
+ For less markup than the most elementary HTML you can have more. SiSU -
+ Structured information, Serialized Units for electronic documents, is an
+ information structuring, transforming, publishing and search framework with the
+ following features:
+
+ (i) markup syntax: (a) simpler than html, (b) mnemonic, influenced by
+ mail/messaging/wiki markup practices, (c) human readable, and easily writable,
+
+ (ii) (a) minimal markup requirement, (b) single file marked up for multiple outputs,
+
+ * documents are prepared in a single UTF-8 file using a minimalistic mnemonic
+ syntax. Typical literature, documents like "War and Peace" require almost no
+ markup, and most of the headers are optional.
+
+ * markup is easily readable/parsed by the human eye, (basic markup is simpler
+ and more sparse than the most basic html), [this may also be converted to XML
+ representations of the same input/source document].
+
+ * markup defines document structure (this may be done once in a header
+ pattern-match description, or for heading levels individually); basic text
+ attributes (bold, italics, underscore, strike-through etc.) as required; and
+ semantic information related to the document (header information, extended
+ beyond the Dublin core and easily further extended as required); the headers
+ may also contain processing instructions.
+
+ (iii) (a) multiple output formats, including amongst others: plaintext (UTF-8);
+ html; (structured) XML; ODF (Open Document text); EPUB; LaTeX; PDF (via LaTeX);
+ SQL type databases (currently PostgreSQL and SQLite). SiSU produces:
+ concordance files; document content certificates (md5 or sha256 digests of
+ headings, paragraphs, images etc.) and html manifests (and sitemaps of
+ content). (b) takes advantage of the strengths implicit in these very different
+ output types, (e.g. PDFs produced using typesetting of LaTeX, databases
+ populated with documents at an individual object/paragraph level, making
+ possible granular search (and related possibilities))
+
+ (iv) outputs share a common numbering system (dubbed "object citation
+ numbering" (ocn)) that is meaningful (to man and machine) across various
+ digital outputs whether paper, screen, or database oriented, (PDF, html, XML,
+ EPUB, sqlite, postgresql), this numbering system can be used to reference
+ content.
+
+ (v) SQL databases are populated at an object level (roughly headings,
+ paragraphs, verse, tables) and become searchable with that degree of
+ granularity, the output information provides the object/paragraph numbers which
+ are relevant across all generated outputs; it is also possible to look at just
+ the matching paragraphs of the documents in the database; [output indexing also
+ work well with search indexing tools like hyperesteier].
+
+ (vi) use of semantic meta-tags in headers permit the addition of semantic
+ information on documents, (the available fields are easily extended)
+
+ (vii) creates organised directory/file structure for (file-system) output,
+ easily mapped with its clearly defined structure, with all text objects
+ numbered, you know in advance where in each document output type, a bit of text
+ will be found (e.g. from an SQL search, you know where to go to find the
+ prepared html output or PDF etc.)... there is more; easy directory management
+ and document associations, the document preparation (sub-)directory may be used
+ to determine output (sub-)directory, the skin used, and the SQL database used,
+
+ (viii) "Concordance file" wordmap, consisting of all the words in a document
+ and their (text/ object) locations within the text, (and the possibility of
+ adding vocabularies),
+
+ (ix) document content certification and comparison considerations: (a) the
+ document and each object within it stamped with an sha256 hash making it
+ possible to easily check or guarantee that the substantive content of a document
+ is unchanged, (b) version control, documents integrated with time based source
+ control system, default RCS or CVS with use of $Id$ tag, which SiSU checks
+
+ (x) SiSU's minimalist markup makes for meaningful "diffing" of the substantive
+ content of markup-files,
+
+ (xi) easily skinnable, document appearance on a project/site wide, directory
+ wide, or document instance level easily controlled/changed,
+
+ (xii) in many cases a regular expression may be used (once in the document
+ header) to define all or part of a documents structure obviating or reducing
+ the need to provide structural markup within the document,
+
+ (xiii) prepared files may be batch process, documents produced are static files
+ so this needs to be done only once but may be repeated for various reasons as
+ desired (updated content, addition of new output formats, updated technology
+ document presentations/representations)
+
+ (xiv) possible to pre-process, which permits: the easy creation of standard
+ form documents, and templates/term-sheets, or; building of composite documents
+ (master documents) from other sisu marked up documents, or marked up parts,
+ i.e. import documents or parts of text into a main document should this be
+ desired
+
+ there is a considerable degree of future-resilience, output representations are
+ "upgradeable", and new document formats may be added.
+
+ (xv) there is a considerable degree of future-resilience, output representations
+ are "upgradeable", and new document formats may be added: (a) modular, (thanks
+ in no small part to Ruby) another output format required, write another
+ module.... (b) easy to update output formats (eg html, XHTML, LaTeX/PDF
+ produced can be updated in program and run against whole document set), (c)
+ easy to add, modify, or have alternative syntax rules for input, should you
+ need to,
+
+ (xvi) scalability, dependent on your file-system (ext3, Reiserfs, XFS,
+ whatever) and on the relational database used (currently Postgresql and
+ SQLite), and your hardware,
+
+ (xvii) only marked up files need be backed up, to secure the larger document
+ set produced,
+
+ (xviii) document management,
+
+ (xix) Syntax highlighting for SiSU markup is available for a number of text
+ editors.
+
+ (xx) remote operations: (a) run SiSU on a remote server, (having prepared sisu
+ markup documents locally or on that server, i.e. this solution where sisu is
+ installed on the remote server, would work whatever type of machine you chose
+ to prepare your markup documents on), (b) generated document outputs may be
+ posted by sisu to remote sites (using rsync/scp) (c) document source (plaintext
+ utf-8) if shared on the net may be identified by its url and processed locally
+ to produce the different document outputs.
+
+ (xxi) document source may be bundled together (automatically) with associated
+ documents (multiple language versions or master document with inclusions) and
+ images and sent as a zip file called a sisupod, if shared on the net these too
+ may be processed locally to produce the desired document outputs, these may be
+ downloaded, shared as email attachments, or processed by running sisu against
+ them, either using a url or the filename.
+
+ (xxii) for basic document generation, the only software dependency is Ruby, and
+ a few standard Unix tools (this covers plaintext, html, XML, ODF, EPUB, LaTeX).
+ To use a database you of course need that, and to convert the LaTeX generated
+ to PDF, a LaTeX processor like tetex or texlive.
+
+ as a developers tool it is flexible and extensible
+
+**** description
+
+ SiSU ("SiSU information Structuring Universe" or "Structured information,
+ Serialized Units"),1 is a Unix command line oriented framework for document
+ structuring, publishing and search. Featuring minimalistic markup, multiple
+ standard outputs, a common citation system, and granular search. Using markup
+ applied to a document, SiSU can produce plain text, HTML, XHTML, XML,
+ OpenDocument, LaTeX or PDF files, and populate an SQL database with objects2
+ (equating generally to paragraph-sized chunks) so searches may be performed and
+ matches returned with that degree of granularity (e.g. your search criteria is
+ met by these documents and at these locations within each document). Document
+ output formats share a common object numbering system for locating content.
+ This is particularly suitable for "published" works (finalized texts as opposed
+ to works that are frequently changed or updated) for which it provides a fixed
+ means of reference of content. How it works
+
+ SiSU markup is fairly minimalistic, it consists of: a (largely optional)
+ document header, made up of information about the document (such as when it was
+ published, who authored it, and granting what rights) and any processing
+ instructions; and markup within text which is related to document structure and
+ typeface. SiSU must be able to discern the structure of a document, (text
+ headings and their levels in relation to each other), either from information
+ provided in the instruction header or from markup within the text (or from a
+ combination of both). Processing is done against an abstraction of the document
+ comprising of information on the document's structure and its objects,2 which
+ the program serializes (providing the object numbers) and which are assigned
+ hash sum values based on their content. This abstraction of information about
+ document structure, objects, (and hash sums), provides considerable flexibility
+ in representing documents different ways and for different purposes (e.g.
+ search, document layout, publishing, content certification, concordance etc.),
+ and makes it possible to take advantage of some of the strengths of established
+ ways of representing documents, (or indeed to create new ones).
+
+ 1. also chosen for the meaning of the Finnish term "sisu".
+
+ 2 objects include: headings, paragraphs, verse, tables, images, but not
+ footnotes/endnotes which are numbered separately and tied to the object from
+ which they are referenced.
+
+ More information on SiSU provided at: <www.sisudoc.org/sisu/SiSU>
+
+ SiSU was developed in relation to legal documents, and is strong across a wide
+ variety of texts (law, literature...(humanities, law and part of the social
+ sciences)). SiSU handles images but is not suitable for formulae/ statistics,
+ or for technical writing at this time.
+
+ SiSU has been developed and has been in use for several years. Requirements to
+ cover a wide range of documents within its use domain have been explored.
+
+ <ralph@amissah.com>
+ <ralph.amissah@gmail.com>
+ <sisu@lists.sisudoc.org>
+ <https://lists.sisudoc.org/listinfo/sisu>
+ 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
+ <https://www.sisudoc.org/>
+
+*** 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: <https://rake.rubyforge.org/> <https://rubyforge.org/frs/?group_id=50>
+
+***** installation with setup.rb
+
+ this is a three step process, in the root directory of the unpacked *SiSU* as
+ root type:
+
+ ruby setup.rb config
+ ruby setup.rb setup
+ #[as root:]
+ ruby setup.rb install
+
+ further information:
+ <https://i.loveruby.net/en/projects/setup/>
+ <https://i.loveruby.net/en/projects/setup/doc/usage.html>
+
+ ruby setup.rb config && ruby setup.rb setup && sudo ruby setup.rb install
+
+**** Debian install
+
+ *SiSU* is available off the *Debian* archives. It should necessary only to run
+ as root, Using apt-get:
+
+ apt-get update
+
+ apt get install sisu-complete
+
+ (all sisu dependencies should be taken care of)
+
+ If there are newer versions of *SiSU* upstream, they will be available by
+ adding the following to your sources list /etc/apt/sources.list
+
+ #/etc/apt/sources.list
+
+ deb 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:
+ <https://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&subword=1&version=all&release=all&keywords=sisu>]
+ [^1] install it using apt-get, aptitude or alternative *Debian* install tools.
+
+**** Arch Linux
+
+*** sisu markup :sisu:
+
+**** markup :markup:
+***** sisu document parts
+ - header
+ - metadata
+ - make instructionS
+ - substantive (& other) content
+ (sisu markup)
+ - endnotes
+ (markup within substantive content)
+ - glossary
+ (section, special markup)
+ - bibliography
+ (section, special markup)
+ - book index
+ (markup attached to substantive content objects)
+
+ |---------------------+-----------------------------------------------------------------------+------------------------+--------|
+ | header | sisu /header markup/ | markup | |
+ | - metadata | | | |
+ | - make instructions | | | |
+ |---------------------+-----------------------------------------------------------------------+------------------------+--------|
+ | substantive content | sisu /content markup/ | markup | output |
+ | | headings (providing document structure), paragraphs, | (regular content) | |
+ | | blocks (code, poem, group, table) | | |
+ |---------------------+-----------------------------------------------------------------------+------------------------+--------|
+ | endnotes | markup within substantive content | markup | output |
+ | | (extracted from sisu /content markup/) | (from regular content) | |
+ |---------------------+-----------------------------------------------------------------------+------------------------+--------|
+ | glossary | identify special section, regular /content markup/ | markup | output |
+ |---------------------+-----------------------------------------------------------------------+------------------------+--------|
+ | bibliography | identify section, special /bibliography markup/ | markup | output |
+ |---------------------+-----------------------------------------------------------------------+------------------------+--------|
+ | book index | extracted from markup attached to related substantive content objects | markup | output |
+ | | (special tags in sisu /content markup/) | (from regular content) | |
+ |---------------------+-----------------------------------------------------------------------+------------------------+--------|
+ | metadata | | (from regular header) | output |
+ |---------------------+-----------------------------------------------------------------------+------------------------+--------|
+
+***** structure - headings, levels
+ - headings (A-D, 1-3)
+
+ 'A~ ' NOTE title level
+
+ 'B~ ' NOTE optional
+ 'C~ ' NOTE optional
+ 'D~ ' NOTE optional
+
+ '1~ ' NOTE chapter level
+ '2~ ' NOTE optional
+ '3~ ' NOTE optional
+
+ * node
+ * parent
+ * children
+
+***** font face NOTE open & close marks, inline within paragraph
+ * emphasize '*{ ... }*' NOTE configure whether bold italics or underscore, default bold
+ * bold '!{ ... }!'
+ * italics '/{ ... }/'
+ * underscore '_{ ... }_'
+ * superscript '^{ ... }^'
+ * subscript ',{ ... },'
+ * strike '-{ ... }-'
+ * add '+{ ... }+'
+ * monospace '#{ ... }#'
+
+***** para
+ NOTE paragraph controls are at the start of a paragraph
+ * a para is a block of text separated from others by an empty line
+ * indent
+ * default, all '_1 ' up to '_9 '
+ * first line hang '_1_0 '
+ * first line indent further '_0_1 '
+ * bullet
+ [levels 1-6]
+ '_* '
+ '_1* '
+ '_2* '
+ * numbered list
+ [levels 1-3]
+ '# '
+
+***** blocks
+ NOTE text blocks that are not to be treated in the way that ordinary paragraphs would be
+ * code
+ * [type of markup if any]
+ * poem
+ * group
+ * alt
+ * tables
+
+***** notes (footnotes/ endnotes)
+ NOTE inline within paragraph at the location where the note reference is to occur
+ * footnotes '~{ ... }~'
+ * [bibliography] [NB N/A not implemented]
+
+***** links, linking
+ * links - external, web, url
+ * links - internal
+
+***** images [multimedia?]
+ * images
+ * [base64 inline] [N/A not implemented]
+
+***** object numbers
+ * ocn (object numbers)
+ automatically attributed to substantive objects, paragraphs, tables, blocks, verse (unless exclude marker provided)
+
+***** contents
+ * toc (table of contents)
+ autogenerated from structure/headings information
+ * index (book index)
+ built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text
+
+***** breaks
+ * line break ' \\ ' inline
+ * page break, column break ' -\\- ' start of line, breaks a column, starts a new column, if using columns, else breaks the page, starts a new page.
+ * page break, page new ' =\\= ' start of line, breaks the page, starts a new page.
+ * horizontal '-..-' start of line, rule page (break) line across page (dividing paragraphs)
+
+***** book type index
+ built from hints in newline text following a paragraph and starting with ={} has identifying rules for main and subsidiary text
+
+ #% comment
+ * comment
+
+ #% misc
+ * term & definition
+
+**** syntax highlighting :syntax:highlighting:
+
+***** vim
+ data/sisu/conf/editor-syntax-etc/vim/
+ data/sisu/conf/editor-syntax-etc/vim/syntax/sisu.vim
+
+***** emacs
+ data/sisu/conf/editor-syntax-etc/emacs/
+ data/sisu/conf/editor-syntax-etc/emacs/sisu-mode.el
+
+*** todo
+ sisu_todo.org
+
+* document header
+
+#+NAME: sisu_document_header
+#+BEGIN_SRC text
+encoding: utf-8
+- Name: SiSU
+
+ - Description: documents, structuring, processing, publishing, search
+ sisu build
+
+ - Author: Ralph Amissah
+ <ralph.amissah@gmail.com>
+
+ - Copyright: (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+ 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2019,
+ 2020, 2021, Ralph Amissah,
+ All Rights Reserved.
+
+ - License: GPL 3 or later:
+
+ SiSU, a framework for document structuring, publishing and search
+
+ Copyright (C) Ralph Amissah
+
+ This program is free software: you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by the Free
+ Software Foundation, either version 3 of the License, or (at your option)
+ any later version.
+
+ This program is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ more details.
+
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <https://www.gnu.org/licenses/>.
+
+ If you have Internet connection, the latest version of the GPL should be
+ available at these locations:
+ <https://www.fsf.org/licensing/licenses/gpl.html>
+ <https://www.gnu.org/licenses/gpl.html>
+
+ <https://www.sisudoc.org/sisu/en/manifest/gpl.fsf.html>
+
+ - SiSU uses:
+ - Standard SiSU markup syntax,
+ - Standard SiSU meta-markup syntax, and the
+ - Standard SiSU object citation numbering and system
+
+ - Homepages:
+ <https://www.sisudoc.org>
+
+ - Git
+ <https://git.sisudoc.org/projects/>
+ <https://git.sisudoc.org/projects/sisu>
+ <https://git.sisudoc.org/projects/sisu-markup>
+#+END_SRC
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-01 21:07:54 +0000