diff options
Diffstat (limited to 'org/sisu_build.org')
| -rw-r--r-- | org/sisu_build.org | 6181 |
1 files changed, 0 insertions, 6181 deletions
diff --git a/org/sisu_build.org b/org/sisu_build.org deleted file mode 100644 index 37463bff..00000000 --- a/org/sisu_build.org +++ /dev/null @@ -1,6181 +0,0 @@ --*- mode: org -*- -#+TITLE: SiSU -#+DESCRIPTION: sisu build -#+FILETAGS: :sisu:build: -#+AUTHOR: Ralph Amissah -#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]] -#+COPYRIGHT: Copyright (C) 2015 - 2020 Ralph Amissah -#+LANGUAGE: en -#+STARTUP: content hideblocks hidestars noindent entitiespretty -#+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil _:nil -:t f:t *:t <:t -#+PROPERTY: header-args :exports code -#+PROPERTY: header-args+ :noweb yes -#+PROPERTY: header-args+ :eval no -#+PROPERTY: header-args+ :results no -#+PROPERTY: header-args+ :cache no -#+PROPERTY: header-args+ :padline no -#+PROPERTY: header-args+ :mkdirp yes - -* sisu git CHANGELOG TODO -** git used TODO - -#+BEGIN_SRC sh -CHL="data/doc/sisu/CHANGELOG" -git log --pretty=format:'-_-%+s %+as %ae%+h%d%+b' --no-merges \ -| sed "/^\\s*$/d" | sed "s/^\([ ]\)*\*/\1-/" | sed "s/ \+$//" | sed "s/^-_-$//" \ -> ${CHL} -#+END_SRC - -** alt - -#+BEGIN_SRC sh -CHL="data/doc/sisu/CHANGELOG" -git log --pretty=format:"-_-_%+s %+as %ae%+h%d%+b" --no-merges \ -> ${CHL} && sed -i '/^$/d; s/^\([ ]\)*\*/\1-/; s/ \+$//; s/^-_-_//' ${CHL} -#+END_SRC - -** +considered+ - -#+BEGIN_SRC sh -LOG_0="changelog_0_" -git log --decorate --sparse --date=short --no-merges --abbrev-commit --format=medium \ -> ${LOG_0} && sed -i 's/^[ ]\+$//; /^$/d' ${LOG_0} -#+END_SRC - -#+BEGIN_SRC sh -LOG_1="changelog_1_" -git log --pretty=format:"%h %as - %s%d <%ae> %+b" --no-merges \ -> ${LOG_1} && sed -i '/^$/d; s/^\([ ]\)*\*/\1-/; s/ \+$//' ${LOG_1} -#+END_SRC - -#+BEGIN_SRC sh -LOG_2="data/doc/sisu/CHANGELOG_1_" -git log --pretty=format:"%h %ad - %s%d [%an]" --graph --date=short --no-merges > ${LOG_2} -#+END_SRC - -* sisu version TODO - -#+HEADER: :tangle ../setup/sisu_version.rb -#+BEGIN_SRC ruby -#% constants -module SiSUversion - SiSU_version = '7.3.0' -end -module Dev - GPGpubKey = '1BB4B289' -end -#+END_SRC - -* +makefile+ :makefile: - -#+HEADER: :NO-tangle ../makefile -#+BEGIN_SRC makefile -#+END_SRC - -* qi (quick install) -** bin - -#+BEGIN_SRC ruby :tangle ../qi :tangle-mode (identity #o755) :shebang #!/usr/bin/env ruby -=begin - -- Description: - -- Homepage: <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/gitweb/?p=code/sisu.git;a=summary> - sisu markup samples are provided/packaged separately as sisu-markup-samples: - <https://git.sisudoc.org/gitweb/?p=doc/sisu-markup-samples.git;a=summary> - WOK -end -task :note_installation do - puts <<-WOK - alternative 0: distribution install, rather than this Rakefile - a distribution install pulls in the many dependencies used by sisu after - initial processing to generate and store output, significant amongst these are - XeTeX & databases (sqlite3 and postgresql) - - alternative 1: gem install, you need to: - create the gemspec; build the gem (from the gemspec); install the gem - which can be done with the single command: - rake gem_create_build_install # (to build and install sisu v5 & sisu v6, alias gemcbi) - separate gems are made/installed for sisu v5 & sisu v6 contained in source: - rake gem_create_build_install_stable # (to build and install sisu v5, alias gem5cbi) - for individual steps (create, build, install) see rake options, rake -T - to specify sisu version for sisu installed via gem - sisu _#{Version_info::Current.setting_stable[:version]}_ --version - to uninstall sisu installed via gem - sudo gem uninstall --verbose sisu - WOK -end -task :note_developer do - puts <<-WOK - - changelogheaders - - sisuversion - sisuversionset - - gemcsn gem5csn gem6csn - gembn gem5bn gem6bn - gemin gem5in gem6in - gembin gem5bin gem6bin - gemcbin gem5cbin gem6cbin - WOK -end - #%% help & system info -task :system_info do - Project_details.system_info -end -task :system_param_ do - Project_details.env.each {|c| puts c.inspect } -end -task :gem_env_ do - Project_details.gem_env -end -task :project_help do - Help.project_help -end -task :tasks do - Help.tasks -end -#+END_SRC - -** Rake & Rant libs - -#+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 - -* nix - -** envrc - -#+HEADER: :tangle ../.envrc -#+BEGIN_SRC sh -NIX_ENFORCE_PURITY=0 -if ! has nix_direnv_version || ! nix_direnv_version 1.4.0; then -# https://github.com/nix-community/nix-direnv - source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/1.4.0/direnvrc" "sha256-4XfVDjv75eHMWN4G725VW7BoOV4Vl3vAabK4YXIfPyE=" -fi -if [ -e .env/local ]; then - source_env_if_exists .env/local || source .env/local -fi -#+END_SRC - -#+HEADER: :tangle ../.envrc-local_ -#+BEGIN_SRC sh -export NIX_PATH=/nix/var/nix/profiles/per-user/root/channels/nixos -#export NIX_PATH=nixpkgs=/nixpkgs-ra/nixpkgs -## reload when these files change -use flake -watch_file flake.nix -eval "$(nix print-dev-env)" -export SisuVER=$(git describe --long --tags | sed 's/^[ a-z_-]\+\([0-9.]\+\)/\1/;s/\([^-]*-g\)/r\1/;s/-/./g') -export SisuSRC=/grotto-ra/repo/git.repo/projects/project-sisu/sisu -export SisuDOC=/grotto-ra/repo/git.repo/projects/project-sisu/susu-markup/sisu-markup-samples/data/samples/current -export SisuOUT=/tmp/sisu/$SisuVER/www -export SisuOUTstatic=/var/www - -export RUBYLIB+=`pwd`/lib -#+END_SRC - -** shell.nix - -*** shell.nix TODO - -#+HEADER: :tangle ../shell.nix -#+HEADER: :shebang #!/usr/bin/env -S nix-shell --pure -#+HEADER: :tangle-mode (identity #o755) -#+BEGIN_SRC nix -{ pkgs ? import <nixpkgs> {} }: -with pkgs; -mkShell { - buildInputs = [ - <<ruby_current>> - <<packages_project_relevant>> - <<packages_build>> - <<packages_extra>> - ]; - shellHook = '' - if [[ -e ".envrc" ]]; then - source .envrc - fi - eval "$(starship init bash)" - ''; -} -#+END_SRC - -#+BEGIN_SRC nix -#!/usr/bin/env -S nix-shell --pure -{ pkgs ? import <nixpkgs> {} }: -with pkgs; -mkShell { - buildInputs = [ - ruby_3_1 - rubyPackages_3_1.rake - rubyPackages_3_1.sqlite3 - rubyPackages_3_1.thor - sqlite - unzip - xz - zip - openssl - #texlive-combined-full - nixFlakes - validatePkgConfig - jq - git - ### candy - starship - ]; - shellHook = '' - if [[ -e ".envrc" ]]; then - source .envrc - fi - eval "$(starship init bash)" - ''; -} -#+END_SRC - - -#+HEADER: :NO-tangle ../shell.nix -#+BEGIN_SRC nix -{ pkgs ? import <nixpkgs> {} }: -pkgs.mkShell { - buildInputs = [ - (import ./packages.nix { inherit pkgs; }) - ]; -} -#+END_SRC - -*** packages.nix -**** default - -#+HEADER: :NO-tangle ../packages.nix -#+BEGIN_SRC nix -{ pkgs ? import <nixpkgs> {} }: -with pkgs; [ - <<ruby_current>> - <<packages_project_relevant>> - <<packages_build>> -] -#+END_SRC - -**** ruby 3.1 - -#+HEADER: :tangle ../nix/pkglst/packages_ruby_3_1.nix -#+BEGIN_SRC nix -{ pkgs ? import <nixpkgs> {} }: -with pkgs; [ - <<ruby_version_3_1>> - <<packages_project_relevant>> - <<packages_build>> -] -#+END_SRC - -**** ruby 3.0 - -#+HEADER: :tangle ../nix/pkglst/packages_ruby_3_0.nix -#+BEGIN_SRC nix -{ pkgs ? import <nixpkgs> {} }: -with pkgs; [ - <<ruby_version_3_0>> - <<packages_project_relevant>> - <<packages_build>> -] -#+END_SRC - -**** ruby 2.6 - -#+HEADER: :tangle ../nix/pkglst/packages_ruby_2_6.nix -#+BEGIN_SRC nix -{ pkgs ? import <nixpkgs> {} }: -with pkgs; [ - <<ruby_version_2_6>> - <<packages_project_relevant>> - <<packages_build>> -] -#+END_SRC - -*** ruby legacy - -#+NAME: ruby_legacy -#+BEGIN_SRC nix -<<ruby_version_2_6>> -#+END_SRC -*** ruby current - -#+NAME: ruby_current -#+BEGIN_SRC nix -<<ruby_version_3_1>> -#+END_SRC - -*** ruby next - -#+NAME: ruby_next -#+BEGIN_SRC nix -<<ruby_version_3_1>> -#+END_SRC - -*** ruby 2.6 - ruby_version_2_6 - -#+NAME: ruby_version_2_6 -#+BEGIN_SRC nix -ruby_2_6 -rubyPackages_2_6.rake -rubyPackages_2_6.sqlite3 -rubyPackages_2_6.thor -#+END_SRC - -*** ruby 3.0 - ruby_version_3_0 - -#+NAME: ruby_version_3_0 -#+BEGIN_SRC nix -ruby_3_0 -rubyPackages_3_0.rake -rubyPackages_3_0.sqlite3 -rubyPackages_3_0.thor -#+END_SRC - -*** ruby 3.1 - ruby_version_3_1 - -#+NAME: ruby_version_3_1 -#+BEGIN_SRC nix -ruby_3_1 -rubyPackages_3_1.rake -rubyPackages_3_1.sqlite3 -rubyPackages_3_1.thor -#+END_SRC - -*** nix related packages - -#+NAME: nix_packages -#+BEGIN_SRC nix -nix -bundler -bundix -#+END_SRC - -*** project relevant packages - -#+NAME: packages_project_relevant -#+BEGIN_SRC nix -sqlite -unzip -xz -zip -openssl -#texlive-combined-full -#+END_SRC - -*** project misc build packages - -#+NAME: packages_build -#+BEGIN_SRC nix -nixFlakes -validatePkgConfig -jq -git -#+END_SRC - -#+NAME: packages_extra -#+BEGIN_SRC nix -starship -#+END_SRC - -* descriptions -** README - -#+HEADER: :tangle ../README -#+BEGIN_SRC md -SISU - README -============= - -INTRODUCTION -************ - -INTRODUCTION - WHAT IS SISU? ----------------------------- - -*SiSU* is a lightweight markup based document creation and publishing framework -that is controlled from the command line. Prepare documents for *SiSU* using -your text editor of choice, then use *SiSU* to generate various output document -formats. - -From a single lightly prepared document (plain-text /UTF-8/) sisu custom builds -several standard output formats which share a common (text object) numbering -system for citation of content within a document (that also has implications -for search). The sisu engine works with an abstraction of the document's -structure and content from which it is possible to generate different forms of -representation of the document. *SiSU* produces: plain-text, /HTML/, /XHTML/, -/XML/, /EPUB/, /ODF/: /ODT/ (Opendocument), /LaTeX/, /PDF/, and populates an -/SQL/ database (/PostgreSQL/ or /SQLite/) with text objects, roughly, paragraph -sized chunks so that document searches are done at this level of granularity. - -Outputs share a common citation numbering system, associated with text objects -and any semantic meta-data provided about the document. - -*SiSU* also provides concordance files, document content certificates and -manifests of generated output. Book indexes may be made. - -Some document markup samples are provided in the package sisu -markup-samples. - -Homepages: -- <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://www.jus.uio.no/sisu> - -DOCUMENT PROCESSING COMMAND FLAGS -................................. - -*-[0-9] [filename/wildcard]* -see --act - -*--ao [filename/wildcard/url]* -assumed for most other flags, creates new intermediate files for processing -(abstract objects, document abstraction) that is used in all subsequent -processing of other output. This step is assumed for most processing flags. To -skip it see -n. Alias -m. - -*--act[s0-9] [filename/wildcard]* ---act0 to --act9 configurable shortcuts for multiple flags, -0 to -9 synonyms, -configure in sisurc.yml; sisu default action on a specified file where no flag -is provided is --act0; --act or --acts for information on current actions -ascribed to --act0 to --act9 - -*--asciidoc [filename/wildcard]* -asciidoc, smart text (not available) - -*-b [filename/wildcard]* -see --xhtml - -*--by-** -see --output-by-* - -*-C* -configure/initialise shared output directory files initialize shared output -directory (config files such as css and dtd files are not updated if they -already exist unless modifier is used). -C --init-site configure/initialise -site more extensive than -C on its own, shared output directory files/force -update, existing shared output config files such as css and dtd files are -updated if this modifier is used. - -*-c [filename/wildcard]* -see --color-toggle - -*--color* -see --color-on - -*--color-off* -turn off color in output to terminal - -*--color-on* -turn on color in output to terminal - -*--color-toggle [filename/wildcard]* -screen toggle ansi screen colour on or off depending on default set (unless -c -flag is used: if sisurc colour default is set to 'true', output to screen will -be with colour, if sisurc colour default is set to 'false' or is undefined -screen output will be without colour). Alias -c - -*--configure* -configure/initialise shared output directory files initialize shared output -directory (config files such as css and dtd files are not updated if they -already exist unless modifier is used). The equivalent of: -C --init-site -configure/initialise site, more extensive than -C on its own, shared output -directory files/force update, existing shared output config files such as css -and dtd files are updated if -CC is used. - -*--concordance [filename/wildcard]* -produces concordance (wordmap) a rudimentary index of all the words in a -document. (Concordance files are not generated for documents of over 260,000 -words unless this limit is increased in the file sisurc.yml). Alias -w - -*-d [filename/wildcard/url]* -see --docbook - -*--dal [filename/wildcard/url]* -(abstract objects, document abstraction renamed abstract objects in sisu5) see ---ao - -*--delete [filename/wildcard]* -see --zap - -*--digests [filename/wildcard/url]* -document digest or document content certificate ( DCC ) as sha digest tree of -the document: the digest for the document, and digests for each object -contained within the document (together with information on software versions -that produced it) (digest.txt). --digests -V for verbose digest output to -screen. - -*--docbook [filename/wildcard/url]* -docbook xml - -*--dom [filename/wildcard/url]* -see --xml-dom - -*--dump[=directory_path] [filename/wildcard]* -places output in directory specified, if none is specified in the current -directory (pwd). Unlike using default settings /HTML/ files have embedded css. -Compare --redirect - -*-e [filename/wildcard]* -see --epub - -*--epub [filename/wildcard]* -produces an epub document, [sisu version >=2 ] (filename.epub). Alias -e - -*--errors-as-warnings* -override stop processing on error. Alias --no-stop - -*--exc-** -exclude output feature, overrides configuration settings --exc-numbering, see ---exc-ocn; --exc-ocn, (exclude "object citation numbering", (switches off -object citation numbers), affects html (seg, scroll), epub, xhtml, xml, pdf) ; ---exc-toc, (exclude table of contents, affects html (scroll), epub, pdf) ; ---exc-links-to-manifest, --exc-manifest-links, (exclude links to manifest, -affects html (seg, scroll)); --exc-search-form, (exclude search form, affects -html (seg, scroll), manifest); --exc-minitoc, (exclude mini table of contents, -affects html (seg), concordance, manifest); --exc-manifest-minitoc, (exclude -mini table of contents, affects manifest); --exc-html-minitoc, (exclude mini -table of contents, affects html (seg), concordance); --exc-html-navigation, -(exclude navigation, affects html (seg)); --exc-html-navigation-bar, (exclude -navigation bar, affects html (seg)); --exc-html-search-form, (exclude search -form, affects html (seg, scroll)); --exc-html-right-pane, (exclude right -pane/column, affects html (seg, scroll)); --exc-html-top-band, (exclude top -band, affects html (seg, scroll), concordance (minitoc forced on to provide seg -navigation)); --exc-segsubtoc (exclude sub table of contents, affects html -(seg), epub) ; see also --inc-* - -*-F [--webserv=webrick]* -see --sample-search-form - -*-f [optional string part of filename]* -see --find - -*--fictionbook [filename/wildcard/url]* -fictionbook xml (not available) - -*--find [optional string part of filename]* -see --glob - -*-G [optional string part of filename]* -see --glob - -*-g [filename/wildcard]* -see --git - -*--git [filename/wildcard]* -produces or updates markup source file structure in a git repo (experimental -and subject to change). Alias -g - -*--glob [optional string part of filename]* -without match string, glob all .sst .ssm files in directory (including language -subdirectories). With match string, find files that match given string in -directory (including language subdirectories). Alias -G, -f, --find - -*-h [filename/wildcard]* -see --html - -*--harvest *.ss[tm]* -makes two lists of sisu output based on the sisu markup documents in a -directory: list of author and authors works (year and titles), and; list by -topic with titles and author. Makes use of header metadata fields (author, -title, date, topic_register). Can be used with maintenance (-M) and remote -placement (-R) flags. - -*--html [filename/wildcard]* -produces html output, in two forms (i) segmented text with table of contents -(toc.html and index.html) and (ii) the document in a single file (scroll.html). -Alias -h - -*--html-scroll [filename/wildcard]* -produces html output, the document in a single file (scroll.html) only. Compare ---html-seg and --html - -*--html-seg [filename/wildcard]* -produces html output, segmented text with table of contents (toc.html and -index.html). Compare --html-scroll and --html - -*--html-strict [filename/wildcard]* -produces html with --strict option. see --strict - -*-I [filename/wildcard]* -see --texinfo - -*-i [filename/wildcard]* -see --manpage - -*--i18n-** -these flags affect output by filetype and filename): --i18n-mono -(--monolingual) output filenames without language code for default language -('en' or as set); --i18n-multi (--multilingual) language code provided as part -of the output filename, this is the default. Where output is in one language -only the language code may not be desired. see also --output-by-* - -*--inc-** -include output feature, overrides configuration settings, (usually the default -if none set), has precedence over --exc-* (exclude output feature). Some detail -provided under --exc-*, see --exc-* - -*-j [filename/wildcard]* -copies images associated with a file for use by html, xhtml & xml outputs -(automatically invoked by --dump & redirect). - -*-k* -see --color-off - -*--keep-processing-files [filename/wildcard/url]* -see --maintenance - -*-M [filename/wildcard/url]* -see --maintenance - -*-m [filename/wildcard/url]* -see --dal (document abstraction level/layer) - -*--machine [filename/wildcard/url]* -see --dal (document abstraction level/layer) - -*--maintenance [filename/wildcard/url]* -maintenance mode, interim processing files are preserved and their locations -indicated. (also see -V). Aliases -M and --keep-processing-files. - -*--manifest [filename/wildcard]* -produces an html summary of output generated (hyperlinked to content) and -document specific metadata (sisu_manifest.html). This step is assumed for most -processing flags. - -*--manpage [filename/wildcard]* -produces man page of file, not suitable for all outputs. Alias -i - -*--markdown [filename/wildcard/url]* -markdown smart text (not available) - -*--monolingual* -see --i18n-* - -*--multilingual* -see --i18n-* - -*-N [filename/wildcard/url]* -see --digests - -*-n [filename/wildcard/url]* -skip the creation of intermediate processing files (document abstraction) if -they already exist, this skips the equivalent of -m which is otherwise assumed -by most processing flags. - -*--no-** -see --exc-* - -*--no-stop* -override stop processing on error. Alias --erros-as-warnings - -*--numbering* -turn on "object citation numbers". See --inc-ocn and --exc-ocn - -*-o [filename/wildcard/url]* -see --odt - -*--ocn* -"object citation numbers". See --inc-ocn and --exc-ocn - -*--odf [filename/wildcard/url]* -see --odt - -*--odt [filename/wildcard/url]* -output basic document in opendocument file format (opendocument.odt). Alias -o - -*--output-by-** -select output directory structure from 3 alternatives: --output-by-language, -(language directory (based on language code) with filetype (html, epub, pdf -etc.) subdirectories); --output-by-filetype, (filetype directories with -language code as part of filename); --output-by-filename, (filename directories -with language code as part of filename). This is configurable. Alias --by-* - -*-P [language_directory/filename language_directory]* -see --po4a - -*-p [filename/wildcard]* -see --pdf - -*--papersize-(a4|a5|b5|letter|legal)* -in conjunction with --pdf set pdf papersize, overriding any configuration -settings, to set more than one papersize repeat the option --pdf --papersize-a4 ---papersize-letter. See also --papersize=* - -*--papersize=a4,a5,b5,letter,legal* in conjunction with --pdf set pdf -papersize, overriding any configuration settings, to set more than one -papersize list after the equal sign with a comma separator ---papersize=a4,letter. See also --papersize-* - -*--pdf [filename/wildcard]* -produces /LaTeX/ pdf (portrait.pdf & landscape.pdf). Orientation and papersize -may be set on the command-line. Default paper size is set in config file, or -document header, or provided with additional command line parameter, e.g. ---papersize-a4 preset sizes include: 'A4', U.S. 'letter' and 'legal' and book -sizes 'A5' and 'B5' (system defaults to A4), and; --landscape or --portrait, -so: e.g. "sisu --pdf-a4 --pdf-letter --landscape --verbose [filename/wildcard]" -or "sisu --pdf --landscape --a4 --letter --verbose [filename/wildcard]". --pdf -defaults to both landscape & portrait output, and a4 if no other papersizes are -configured. Related options --pdf-landscape --pdf-portrait --pdf-papersize-* ---pdf-papersize=[list]. Alias -p - -*--pdf-l [filename/wildcard]* -See --pdf-landscape - -*--pdf-landscape [filename/wildcard]* -sets orientation, produces /LaTeX/ pdf landscape.pdf. Default paper size is set -in config file, or document header, or provided with additional command line -parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter' and -'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related options ---pdf --pdf-portrait. See also --papersize-* or --papersize=[list]. Alias ---pdf-l or in conjunction with --pdf --landscape - -*--pdf-p [filename/wildcard]* -See --pdf-portrait - -*--pdf-portrait [filename/wildcard]* -sets orientation, produces /LaTeX/ pdf portrait.pdf.pdf. Default paper size is -set in config file, or document header, or provided with additional command -line parameter, e.g. --papersize-a4 preset sizes include: 'A4', U.S. 'letter' -and 'legal' and book sizes 'A5' and 'B5' (system defaults to A4). Related -options --pdf --pdf-landscape. See also --papersize-* or --papersize=[list]. -Alias --pdf-p or in conjunction with --pdf --portrait - -*--pg-[instruction] [filename]* -database /PostgreSQL/ ( --pgsql may be used instead) possible instructions, -include: --pg-createdb; --pg-create; --pg-dropall; --pg-import [filename]; ---pg-update [filename]; --pg-remove [filename]; see database section below. - -*--po [language_directory/filename language_directory]* -see --po4a - -*--po4a [language_directory/filename language_directory]* -produces .pot and po files for the file in the languages specified by the -language directory. *SiSU* markup is placed in subdirectories named with the -language code, e.g. en/ fr/ es/. The sisu config file must set the output -directory structure to multilingual. v3, experimental - -*-Q [filename/wildcard]* -see --qrcode - -*-q [filename/wildcard]* -see --quiet - -*--qrcode [filename/wildcard]* -generate QR code image of metadata (used in manifest). - -*--quiet [filename/wildcard]* -quiet less output to screen. - -*-R [filename/wildcard]* -see --rsync - -*-r [filename/wildcard]* -see --scp - -*--redirect[=directory_path] [filename/wildcard]* -places output in subdirectory under specified directory, subdirectory uses the -filename (without the suffix). If no output directory is specified places the -subdirectory under the current directory (pwd). Unlike using default settings -/HTML/ files have embedded css. Compare --dump - -*--rst [filename/wildcard/url]* -ReST (rST restructured text) smart text (not available) - -*--rsync [filename/wildcard]* -copies sisu output files to remote host using rsync. This requires that -sisurc.yml has been provided with information on hostname and username, and -that you have your "keys" and ssh agent in place. Note the behavior of rsync -different if -R is used with other flags from if used alone. Alone the rsync ---delete parameter is sent, useful for cleaning the remote directory (when -R -is used together with other flags, it is not). Also see --scp. Alias -R - -*-S* -see --sisupod - -*-S [filename/wildcard]* -see --sisupod - -*-s [filename/wildcard]* -see --source - -*--sample-search-form [--db-(pg|sqlite)]* -generate examples of (naive) cgi search form for /SQLite/ or PgSQL depends on -your already having used sisu to populate an /SQLite/ or PgSQL database, (the -/SQLite/ version scans the output directories for existing sisu_sqlite -databases, so it is first necessary to create them, before generating the -search form) see --sqlite & --pg and the database section below. Optional -additional parameters: --db-user='www-data'. The samples are dumped in the -present work directory which must be writable, (with screen instructions given -that they be copied to the cgi-bin directory). Alias -F - -*--sax [filename/wildcard/url]* -see --xml-sax - -*--scp [filename/wildcard]* -copies sisu output files to remote host using scp. This requires that -sisurc.yml has been provided with information on hostname and username, and -that you have your "keys" and ssh agent in place. Also see --rsync. Alias -r - -*--sha256* -set hash digest where used to sha256 - -*--sha512* -set hash digest where used to sha512 - -*--sqlite-[instruction] [filename]* -database type set to /SQLite/, this produces one of two possible databases, -without additional database related instructions it produces a discreet -/SQLite/ file for the document processed; with additional instructions it -produces a common /SQLite/ database of all processed documents that (come from -the same document preparation directory and as a result) share the same output -directory base path (possible instructions include: --sqlite-createdb; ---sqlite-create; --sqlite-dropall; --sqlite-import [filename]; --sqlite-update -[filename]; --sqlite-remove [filename]); see database section below. - -*--sisupod* -produces a sisupod a zipped sisu directory of markup files including sisu -markup source files and the directories local configuration file, images and -skins. Note: this only includes the configuration files or skins contained in -./_sisu not those in ~/.sisu -S [filename/wildcard] option. Note: (this option -is tested only with zsh). Alias -S - -*--sisupod [filename/wildcard]* -produces a zipped file of the prepared document specified along with associated -images, by default named sisupod.zip they may alternatively be named with the -filename extension .ssp This provides a quick way of gathering the relevant -parts of a sisu document which can then for example be emailed. A sisupod -includes sisu markup source file, (along with associated documents if a master -file, or available in multilingual versions), together with related images and -skin. *SiSU* commands can be run directly against a sisupod contained in a -local directory, or provided as a url on a remote site. As there is a security -issue with skins provided by other users, they are not applied unless the flag ---trust or --trusted is added to the command instruction, it is recommended -that file that are not your own are treated as untrusted. The directory -structure of the unzipped file is understood by sisu, and sisu commands can be -run within it. Note: if you wish to send multiple files, it quickly becomes -more space efficient to zip the sisu markup directory, rather than the -individual files for sending). See the -S option without [filename/wildcard]. -Alias -S - -*--source [filename/wildcard]* -copies sisu markup file to output directory. Alias -s - -*--strict* -together with --html, produces more w3c compliant html, for example not having -purely numeric identifiers for text, the location object url#33 becomes url#o33 - -*-T [filename/wildcard (*.termsheet.rb)]* -standard form document builder, preprocessing feature - -*-t [filename/wildcard]* -see --txt - -*--texinfo [filename/wildcard]* -produces texinfo and info file, (view with pinfo). Alias -I - -*--textile [filename/wildcard/url]* -textile smart text (not available) - -*--txt [filename/wildcard]* -produces /plaintext/ with Unix linefeeds and without markup, (object numbers -are omitted), has footnotes at end of each paragraph that contains them [ -A -for equivalent dos (linefeed) output file] [see -e for endnotes]. (Options -include: --endnotes for endnotes --footnotes for footnotes at the end of each -paragraph --unix for unix linefeed (default) --msdos for msdos linefeed). Alias --t - -*--txt-asciidoc [filename/wildcard]* -see --asciidoc - -*--txt-markdown [filename/wildcard]* -see --markdown - -*--txt-rst [filename/wildcard]* -see --rst - -*--txt-textile [filename/wildcard]* -see --textile - -*-U [filename/wildcard]* -see --urls - -*-u [filename/wildcard]* -provides url mapping of output files for the flags requested for processing, -also see -U - -*--urls [filename/wildcard]* -prints url output list/map for the available processing flags options and -resulting files that could be requested, (can be used to get a list of -processing options in relation to a file, together with information on the -output that would be produced), -u provides url output mapping for those flags -requested for processing. The default assumes sisu_webrick is running and -provides webrick url mappings where appropriate, but these can be switched to -file system paths in sisurc.yml. Alias -U - -*-V* -on its own, provides *SiSU* version and environment information (sisu --help -env) - -*-V [filename/wildcard]* -even more verbose than the -v flag. - -*-v* -on its own, provides *SiSU* version information - -*-v [filename/wildcard]* -see --verbose - -*--verbose [filename/wildcard]* -provides verbose output of what is being generated, where output is placed (and -error messages if any), as with -u flag provides a url mapping of files created -for each of the processing flag requests. Alias -v - -*--very-verbose [filename/wildcard]* -provides more verbose output of what is being generated. See --verbose. Alias --V - -*--version* -sisu version - -*-W* -see --webrick - -*-w [filename/wildcard]* -see --concordance - -*--webrick* -starts ruby' s webrick webserver points at sisu output directories, the default -port is set to 8081 and can be changed in the resource configuration files. -[tip: the webrick server requires link suffixes, so html output should be -created using the -h option rather than -H ; also, note -F webrick ]. Alias -W - -*--wordmap [filename/wildcard]* -see --concordance - -*--xhtml [filename/wildcard]* -produces xhtml//XML/ output for browser viewing (sax parsing). Alias -b - -*--xml-dom [filename/wildcard]* -produces /XML/ output with deep document structure, in the nature of dom. Alias --X - -*--xml-sax [filename/wildcard]* -produces /XML/ output shallow structure (sax parsing). Alias -x - -*-X [filename/wildcard]* -see --xml-dom - -*-x [filename/wildcard]* -see --xml-sax - -*-Y [filename/wildcard]* -produces a short sitemap entry for the document, based on html output and the -sisu_manifest. --sitemaps generates/updates the sitemap index of existing -sitemaps. (Experimental, [g,y,m announcement this week]) - -*-y [filename/wildcard]* -see --manifest - -*-Z [filename/wildcard]* -see --zap - -*--zap [filename/wildcard]* -Zap, if used with other processing flags deletes output files of the type about -to be processed, prior to processing. If -Z is used as the lone processing -related flag (or in conjunction with a combination of -[mMvVq]), will remove -the related document output directory. Alias -Z - -COMMAND LINE MODIFIERS ----------------------- - -*--no-ocn* -[with --html --pdf or --epub] switches off /object citation numbering/. Produce -output without identifying numbers in margins of html or /LaTeX//pdf output. - -*--no-annotate* -strips output text of editor endnotes[^*1] denoted by asterisk or dagger/plus -sign - -*--no-asterisk* -strips output text of editor endnotes[^*2] denoted by asterisk sign - -*--no-dagger* -strips output text of editor endnotes[^+1] denoted by dagger/plus sign - -DATABASE COMMANDS ------------------ - -*dbi - database interface* - -*--pg or --pgsql* set for /PostgreSQL/ *--sqlite* default set for /SQLite/ -d -is modifiable with --db=[database type (PgSQL or /SQLite/) ] - -*--pg -v --createall* -initial step, creates required relations (tables, indexes) in existing -/PostgreSQL/ database (a database should be created manually and given the same -name as working directory, as requested) (rb.dbi) [ -dv --createall /SQLite/ -equivalent] it may be necessary to run sisu -Dv --createdb initially NOTE: at -the present time for /PostgreSQL/ it may be necessary to manually create the -database. The command would be 'createdb [database name]' where database name -would be SiSU_[present working directory name (without path)]. Please use only -alphanumerics and underscores. - -*--pg -v --import* -[filename/wildcard] imports data specified to /PostgreSQL/ db (rb.dbi) [ -dv ---import /SQLite/ equivalent] - -*--pg -v --update* -[filename/wildcard] updates/imports specified data to /PostgreSQL/ db (rb.dbi) -[ -dv --update /SQLite/ equivalent] - -*--pg --remove* -[filename/wildcard] removes specified data to /PostgreSQL/ db (rb.dbi) [ -d ---remove /SQLite/ equivalent] - -*--pg --dropall* -kills data" and drops (/PostgreSQL/ or /SQLite/) db, tables & indexes [ -d ---dropall /SQLite/ equivalent] - -The -v is for verbose output. - -COMMAND LINE WITH FLAGS - BATCH PROCESSING -.......................................... - -In the data directory run sisu -mh filename or wildcard eg. "sisu -h cisg.sst" -or "sisu -h *.{sst,ssm}" to produce html version of all documents. - -Running sisu (alone without any flags, filenames or wildcards) brings up the -interactive help, as does any sisu command that is not recognised. Enter to -escape. - -INTRODUCTION TO SISU MARKUP[^3] -------------------------------- - -SUMMARY -....... - -*SiSU* source documents are /plaintext/ (/UTF-8/)[^4] files - -All paragraphs are separated by an empty line. - -Markup is comprised of: - -- at the top of a document, the document header made up of semantic meta-data -about the document and if desired additional processing instructions (such an -instruction to automatically number headings from a particular level down) - -- followed by the prepared substantive text of which the most important single -characteristic is the markup of different heading levels, which define the -primary outline of the document structure. Markup of substantive text includes: - - * heading levels defines document structure - - * text basic attributes, italics, bold etc. - - * grouped text (objects), which are to be treated differently, such as code - blocks or poems. - - * footnotes/endnotes - - * linked text and images - - * paragraph actions, such as indent, bulleted, numbered-lists, etc. - -MARKUP RULES, DOCUMENT STRUCTURE AND METADATA REQUIREMENTS -.......................................................... - -minimal content/structure requirement: - -[metadata] - -A~ (level A [title]) - -1~ (at least one level 1 [segment/(chapter)]) - -structure rules (document heirarchy, heading levels): - -there are two sets of heading levels ABCD (title & parts if any) and 123 -(segment & subsegments if any) - -sisu has the fllowing levels: - -A~ [title] . - required (== 1) followed by B~ or 1~ -B~ [part] * - followed by C~ or 1~ -C~ [subpart] * - followed by D~ or 1~ -D~ [subsubpart] * - followed by 1~ -1~ [segment (chapter)] + - required (>= 1) followed by text or 2~ -text * - followed by more text or 1~, 2~ - or relevant part *() -2~ [subsegment] * - followed by text or 3~ -text * - followed by more text or 1~, 2~ or 3~ - or relevant part, see *() -3~ [subsubsegment] * - followed by text -text * - followed by more text or 1~, 2~ or 3~ or relevant part, see *() - -*(B~ if none other used; - if C~ is last used: C~ or B~; - if D~ is used: D~, C~ or B~) - -- level A~ is the tile and is mandatory -- there can only be one level A~ -- heading levels BCD, are optional and there may be several of each - (where all three are used corresponding to e.g. Book Part Section) - * sublevels that are used must follow each other sequentially - (alphabetically), -- heading levels A~ B~ C~ D~ are followed by other heading levels rather - than substantive text - which may be the subsequent sequential (alphabetic) heading part level - or a heading (segment) level 1~ -- there must be at least one heading (segment) level 1~ - (the level on which the text is segmented, in a book would correspond - to the Chapter level) -- additional heading levels 1~ 2~ 3~ are optional and there may be several - of each -- heading levels 1~ 2~ 3~ are followed by text (which may be followed by - the same heading level) - and/or the next lower numeric heading level (followed by text) - or indeed return to the relevant part level - (as a corollary to the rules above substantive text/ content - must be preceded by a level 1~ (2~ or 3~) heading) - -MARKUP EXAMPLES -............... - - ----------------------------------------- - -ONLINE -...... - -Online markup examples are available together with the respective outputs -produced from <https://www.jus.uio.no/sisu/SiSU/examples.html> 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://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler> - - [10]: for which you may alternatively use the full form author: title: and year: - - [11]: Quixote and Panza, /Taming Windmills/ (1605), pp 1000 - 1001 also, Benkler, - /Wealth of Networks/ (2006), p 1 - #+END_SRC - -** a description - -(emacs:evil mode gifts a "vim" of enticing "alternative" powers! ;) -(vim, my _editor_ of choice also in the emacs environment :) - -*** What is SiSU? - - Multiple output formats with a nod to the strengths of each output format and - the ability to cite text easily across output formats. - -**** debian/control desc - - documents - structuring, publishing in multiple formats and search - SiSU is a lightweight markup based, command line oriented, document - structuring, publishing and search, static content tool for document - collections. - . - With minimal preparation of a plain-text (UTF-8) file, using sisu markup syntax - in your text editor of choice, SiSU can generate various document formats, most - of which share a common object numbering system for locating content, including - plain text, HTML, XHTML, XML, EPUB, OpenDocument text (ODF:ODT), LaTeX, PDF - files, and populate an SQL database with objects (roughly paragraph-sized - chunks) so searches may be performed and matches returned with that degree of - granularity. Think of being able to finely match text in documents, using - common object numbers, across different output formats and across languages if - you have translations of the same document. For search, your criteria is met - by these documents at these locations within each document (equally relevant - across different output formats and languages). To be clear (if obvious) page - numbers provide none of this functionality. Object numbering is particularly - suitable for "published" works (finalized texts as opposed to works that are - frequently changed or updated) for which it provides a fixed means of reference - of content. Document outputs can also share provided semantic meta-data. - . - SiSU also provides concordance files, document content certificates and - manifests of generated output and the means to make book indexes that make use - of its object numbering. - . - Syntax highlighting and folding (outlining) files are provided for the Vim and - Emacs editors. - . - Dependencies for various features are taken care of in sisu related packages. - The package sisu-complete installs the whole of SiSU. - . - Additional document markup samples are provided in the package - sisu-markup-samples which is found in the non-free archive. The licenses for - the substantive content of the marked up documents provided is that provided - by the author or original publisher. - . - SiSU uses utf-8 & parses left to right. Currently supported languages: - am bg bn br ca cs cy da de el en eo es et eu fi fr ga gl he hi hr hy ia is it - ja ko la lo lt lv ml mr nl nn no oc pl pt pt_BR ro ru sa se sk sl sq sr sv ta - te th tk tr uk ur us vi zh (see XeTeX polyglossia & cjk) - . - SiSU works well under po4a translation management, for which an administrative - sample Rakefile is provided with sisu_manual under markup-samples. - -**** take two - - SiSU may be regarded as an open access document publishing platform, applicable - to a modest but substantial domain of documents (typically law and literature, - but also some forms of technical writing), that is tasked to address certain - challenges I identified as being of interest to me over the years in open - publishing. - - The idea and implementation may be of interest to consider as some of the - issues encountered and that it seeks to address are known and common to such - endeavors. Amongst them: - - * how do you ensure what you do now can be read in decades? - * how do you keep up with new changing and technologies? - * do you select a canonical format to represent your documents, if so - what? - * how do you reliably cite (locate) material in different document - representations? - * how do you deal with multilingual texts? - * what of search? - * how are documents contributed to the collection? - - (these questions are selected in to help describe the direction of efforts with - regard to sisu). - - My Dabblings in the Domain of Open Publishing - --------------------------------------------- - - The system is called SiSU, it is an offshoot of my early efforts at finding out - what to make of the web, that started at the University of Tromsø in 1993 (an - early law website Ananse/ International Trade Law Project / Lex Mercatoria). I - have worked on SiSU continually since 1997 and it has been open source in 2005 - (under a license called GPL3+), though I remain its developer. - - In working in this field I have had to address some of the common issues. - - So how do you ensure what you do now can be read in decades to come? There are - alternative solutions. (i) stick with a widely used and not overly complicated - well document open standard, and for that the likes of odf is an excellent - choice (ii) alternatively go for the most basic representation of a document - that meets your needs, in my case based on UTF-8 text and some markup tags, - fairly easily parsable by the human eye and as long as utf8 is in use it will - always be possible to extract the information - - How do you keep up with new changing and technologies? Here my solution has - been to generate new versions of the substantive content so as to always have - the latest document representations available e.g. HTML has changed a lot over - the years, different specifications come out for various formats including ODF, - electronic readers have become an important viewing alternative, introducing - the open reader format EPUB. Output representations are generated from source - documents. Different open document file formats can be produced and databases - and search engines populated. (The source documents and interpreter are all - that are required to re-create site content. Source documents can be made - public or retained privately). The strict separation of a simple source - document from the output produced, means that with updates to SiSU (the - interpreter/processor/generator), outputs can be updated technically as - necessary, and new output formats added when needed. Amongst the output formats - currently supported are HTML, LaTeX generated Pdfs (A4, letter, other; - landscape, portrait), Epub, Open Document Format text. Returning to HTML as an - example, it has changed a lot over the years I have worked with it, this way of - working has meant it is possible to keep producing current versions of HTML, - retaining the original substantive document... and new formats have been added - as thought desired. There is no attempt to make output in different document - formats/ representations look alike let alone identical. Rather the attempt is - to optimize output for the particular document filetype, (there is no reason - why an epub document would look or behave like an open document text or that a - Pdf would look like HTML output; rather PDF is optimized for paper viewing, - HTML for screen etc.) Wherever possible features associated with the - particular output type are taken advantage of. This freedom is made possible to - a large extent by the answer to the question that follows. - - How do you reliably cite (locate) material in different document - representations? The traditional answer has been to have a canonical - publication, and resulting fixed page numbers. This was not a viable solution - for HTML (which changes from one viewer to another and with selectable font - faces & size etc.); nor is it otherwise ideal in an electronic age with the - possibility of presenting/interacting with material/documents in so many - different ways. Why be so restricted? Here my solution has been "object - citation numbering". What the various generated document formats have in - common is a shared object numbering system that identifies the location of text - and that is available for citation purposes. Object numbers are: sequential - numbers assigned to each identified object in a document. Objects are logical - units of text (or equivalent parts of a document), usually paragraphs, but also - document headings, tables, images, in a poem a verse etc. [In an electronic - publishing age are page numbers the best we can come up with? Change font - type, font size, page orientation, paper size (sometimes even the viewer) and - where are you with them? And paper though a favorite medium of mine is no - longer the sole (or sometimes primary) means of interacting with documents/text - or of sharing knowledge] - - What object numbers mean (unlike page numbers) is e.g. - - * if you cite text in any format, the resulting output can be reliably located - in any other document format type. Cite HTML and the reader can choose to - view in Epub or Pdf (the PDFs being an independent output, generated by - book publishing software XeTeX/LaTeX). - - * if you do a search, you can be given a result "index" indicating that your - search criteria is met by these documents, and at these specific locations - within each document, and the "index" is relevant not only for content - within the database, but for all document formats. - - * if you have a translated text prepared for sisu, then your citations are - relevant across languages e.g. you can specify exactly where in a Chinese - document text is to be found. - - * generated document index references & concordance list references etc. are - relevant across all output formats. - - What of search? For search, see the implications of object numbers for search - mentioned above. The system currently loads an SQL server (Postgresql) with - object sized text chunks. It could just as well populate an analytical engine - with larger sections or chapters of text for analytical purposes (such as the - currently popular Elasticsearch), whilst availing itself also of the concept of - objects and object numbers in search results. - - How do you deal with multilingual texts? If you have translated text prepared - for sisu, then your citations are relevant across languages. Object numbers - also provide an easy way to compare, discuss text (translations) across - languages. Text found/cited in one language has the same object number in its - translations, a given paragraph will be the same in another language, just - change the language code. (documents are prepared in UTF-8, current language - restrictions are: through use of LaTeX tools, Polyglosia & CJK (Chinese, - Japanese & Korean), and from the fact that sisu parses left to right) - - How are materials prepared for contribution to the collection? (a) The easiest - solution if the system allows is for submission in the format in which work is - authored, usually a word processor, for which odf may be a decent selection. - (b) I have stuck with enhanced plaintext, UTF-8 with minimal markup. Source - documents are prepared in UTF-8 text, with a minimalist native markup to - indicate the document structure (headings and their relative levels), - footnotes, and other document "features". This markup is easily parsable to the - human eye, and plays well with version control systems. Documents are prepared - in a text editor. Front ends such as markup assistants in a word processor that - can save to sisu text format or other tool whist possible do not exist. [(c) - yet another form of submission for collaborative work are wikis which have - shown their strength in efforts such as Wikipedia.] - - The system has proven to be a good testing ground for ideas and is flexible and - extensible. (things that could usefully be done: apart from a front end for - simpler user interaction; feed text to an analytical search engine, like - Elasticsearch/Lucene; it still needs a bibliography parser (auto-generation of - a bibliography from footnotes); and it might be useful to allow rough auto - translation documents on the fly by passing text through a translator (such as - Google translate)). - - In any event, my resulting technical opinions (in my modest domain of - action) may be regarded as encapsulated within SiSU - [https://www.sisudoc.org/] - - https://www.sisudoc.org/ - https://www.jus.uio.no/sisu/ - - git clone git://git.sisudoc.org/software/sisu --branch upstream - https://git.sisudoc.org/sisu/ - (there may be additional commits in the upstream branch) - git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream - - git clone git://git.sisudoc.org/git/doc/sisu-markup-samples.git --branch upstream - git clone --depth 1 git://git.sisudoc.org/git/doc/sisu-markup-samples.git --branch upstream - Development work is on Linux and the easiest way to install it is through the - Debian Linux package as this takes care of optional external dependencies such - as XeTeX for PDF output and Postgresql or Sqlite for search. - -**** multiple document formats - - Text can be represented in multiple output formats with different - characteristics that are (or may be) regarded as strengths/advantages and - therefore preferred in different contexts. - - Given the different strengths and characteristics of various output formats, it - makes little sense to try too hard to make different representations of a - document look the same. More interesting is have document representations that - take advantage of each given outputs strengths. As valuable if not more so is - the ability to cite, find, discuss text with ease, across the different output - formats. - - For citation across output formats, SiSU uses object citation numbers. - -**** document structure and document objects - - SiSU breaks marked up text into document structure and objects - - Document structure being the document heading hierarchy (having separated out - the document header). - -***** What are document objects? - An object is an identified meaningful unit of a document, most commonly a - paragraph of text, but also for example a table, code block, verse or image. - - SiSU tracks these substantive document units as document objects (and their - relationship to the document structure). - -**** object citation numbers - -***** What are object citation numbers? - - An object citation number is a sequential number assigned to a document object. - - In sisu output documents share this common object numbering system (dubbed - "object citation numbering" (ocn)) that is meaningful (machine & human readable) - across various digital outputs whether paper, screen, or database oriented, - (PDF, html, XML, EPUB, sqlite, postgresql), and across multilingual content if - prepared appropriately. This numbering system can be used to reference content - across output types. - -***** Why might I want object citation numbering? - - The ability to cite and quickly locate text can be invaluable if not essential. - (whether for instruction or discussion). - - In this digital & Internet age we have multiple ways to represent documents and - multiple document output formats as options with different characteristics, - strengths/advantages etc. We need a way to cite text that works and is relevant - independent of the document format used. - - I want to discuss (cite) html text how do I do this? - how do I refer to / cite / discuss text in html? - Issue: html may be viewed online or printed, it is not tied to paper (as - e.g. pdf) and prints differently depending on selected font face and font size. - - I want to discuss (cite) text that is available in multiple formats (e.g. pdf, - epub, html) without having to worry about the output format that is referred - to. - How do I refer to / discuss text that is available in more than one format, - uncertain of what format is preferred, used or available to my colleagues? - e.g. html and epub or pdf have rather different text representations, how do I - discuss ... - - I would like to have a book index that is relevant (can be used) across multiple - output formats (e.g. pdf, epub, html) - - How do I make a book index (or a concordance file) that works across multiple - output formats? - - I would like to have search results indicating where in a document matches are - found and I would like it to be relevant across available output formats (e.g. - pdf, epub, html) - How do I get search results for locations of text within each relevant document - - I would like to be able to discuss a text that has been translated ... - how do I find text across languages? - Where I have a nicely translated document, how do I point to or discuss with my - foreign language counterpart some detail of the text, or, how do I point my - foreign language counterpart to the text I would like to bring to his - attention. - -**** "Granular" Search - - Of interest is the ease of streaming documents to a relational database, at an - object (roughly paragraph) level and the potential for increased precision in - the presentation of matches that results thereby. The ability to serialize - html, LaTeX, XML, SQL, (whatever) is also inherent in / incidental to the - design. - -**** Summary - SiSU information Structuring Universe - Structured information, Serialized Units <www.sisudoc.org> or - <www.jus.uio.no/sisu/> software for electronic texts, document collections, - books, digital libraries, and search, with "atomic search" and text positioning - system (shared text citation numbering: "ocn") - outputs include: plaintext, html, XHTML, XML, ODF (OpenDocument), EPUB, LaTeX, - PDF, SQL (PostgreSQL and SQLite) - -**** SiSU Short Description - - SiSU is a comprehensive future-resilient electronic document management system. - Built-in search capabilities allow you to search across multiple documents and - highlight matches in an easy-to-follow format. Paragraph numbering system - allows you to cite your electronic documents in a consistent manner across - multiple file formats. Multiple format outputs allow you to display your - documents in plain text, PDF (portrait and horizontal), OpenDocument format, - HTML, or e-book reading format (EPUB). Word mapping allows you to easily create - word indexes for your documents. Future-resilient flexibility allows you to - quickly adapt your documents to newer output formats as needed. All these and - many other features are achieved with little or no additional work on your - documents - by marking up the documents with a super simplistic markup - language, leaving the SiSU engine to handle the heavy-lifting processing. - - Potential users of SiSU include individual authors who want to publish their - books or articles electronically to reach a broad audience, web publishers who - want to provide multiple channels of access to their electronic documents, or - any organizations which centrally manage a medium or large set of electronic - documents, especially governmental organizations which may prefer to keep their - documents in easily accessible yet non-proprietary formats. - - SiSU is an Open Source project initiated and led by Ralph Amissah - <ralph.amissah@gmail.com> and can be contacted via mailing list - <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 - -** git -*** gitignore - -#+HEADER: :tangle ../.gitignore -#+BEGIN_SRC sh -# git ls-files --others --exclude-from=.git/info/exclude -* -!README -!COPYRIGHT -!CHANGELOG -!CHANGELOGS/ -!CHANGELOGS/CHANGELOG -!CHANGELOGS/CHANGELOG_v* -!makefile -!Rakefile -!Rantfile -!qi -!setup/ -!setup/* -!version -!version.txt -!conf/ -!conf/** -!*.json -!*.org -!*.rb -!*.txt -!*.yml -!*.nix -!nix/ -!nix/** -!org/ -!bin -!bin/sisu -!bin/sisu-* -!bin/sisugem -!lib -!lib/** -!man -!man/** -!data -!data/doc -!data/doc/** -!data/sisu -!data/sisu/** -!*.sst -!*.ssm -!**/*.sst -!**/*.ssm -!debian/ -!debian/changelog -!debian/compat -!debian/control -!debian/copyright -!debian/gbp.conf -!debian/sisu*.manpages -!debian/sisu*.install -!debian/manpages/ -!debian/manpages/sisu*.7 -!debian/rules -!debian/sisu\.* -!debian/source/ -!debian/source/format -!debian/watch -*~ -*_ -\#* -*.\#* -*.tmp -*_tmp -*.gem -*.gemspec -!sisu.gemspec -*_.rb -*.rb_ -0???-*.patch -*.gz -*.xz -*_ -.* -!.gitignore -!.envrc -#+END_SRC - -##+HEADER: :tangle ../.gitignore -#+BEGIN_SRC sh -# git ls-files --others --exclude-from=.git/info/exclude -,*~ -,*_ -\#* -,*.\#* -,*.tmp -,*_tmp -.* -,*.gem -,*.gemspec -!.gitignore -!.envrc -,*_.rb -,*.rb_ -.pc -0???-*.patch -,*.gz -,*.xz -#+END_SRC - -*** todo - sisu_todo.org - -* document header - -#+NAME: sisu_document_header -#+BEGIN_SRC text -encoding: utf-8 -- Name: SiSU - - - Description: documents, structuring, processing, publishing, search - sisu build - - - Author: Ralph Amissah - <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 |