aboutsummaryrefslogtreecommitdiffhomepage
path: root/org/sisu_build.org
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2023-01-30 21:46:59 -0500
committerRalph Amissah <ralph.amissah@gmail.com>2023-02-08 16:31:55 -0500
commit615892da80afb671040c8be5d89430ae2fafe180 (patch)
tree8926f3a0f91bdbe9482b1337e849cbd42c980e20 /org/sisu_build.org
parentversion & changelog, open commit window (diff)
nix flake, install & devShells etc.
Diffstat (limited to 'org/sisu_build.org')
-rw-r--r--org/sisu_build.org6181
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
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-13 09:15:02 +0000