Rakefile to assist in placing sisu markup under po4a management (sisu_manual)sisu_4.2.4

* Provided as an example with sisu_manual
* fairly generic, but potentially dangerous, can be used to place sisu markup
  source translations under po4a management, but user needs to know what this
  is, (and how to set it up, hence sisu_manual as an example (despite the lack
  of translations)) as can clobber/destroy files that are not managed by po4a.

4 files changed, 423 insertions, 0 deletions

diff --git a/data/doc/sisu/CHANGELOG_v4 b/data/doc/sisu/CHANGELOG_v4
index 5b60469d..1e28e882 100644
--- a/data/doc/sisu/CHANGELOG_v4
+++ b/data/doc/sisu/CHANGELOG_v4
@@ -38,6 +38,15 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_4.2.4.orig.tar.xz
   * use of language sub-dir for source sisu markup suited to permitting
     translation management by po4a
   * sisurc.yml minor
+  * Rakefile to help place sisu markup in a source language directory under po4a
+    management
+
+* Rakefile to assist in placing sisu markup under po4a management (sisu_manual)
+  * Provided as an example with sisu_manual
+  * fairly generic, but potentially dangerous, can be used to place sisu markup
+    source translations under po4a management, but user needs to know what this
+    is, (and how to set it up, hence sisu_manual as an example (despite the lack
+    of translations)) as can clobber/destroy files that are not managed by po4a.
 
 * dal, objects, store book index as hash (simplify downstream processing), and
   associated downstream processing change from v5
diff --git a/data/doc/sisu/CHANGELOG_v5 b/data/doc/sisu/CHANGELOG_v5
index 35006465..9614e6c3 100644
--- a/data/doc/sisu/CHANGELOG_v5
+++ b/data/doc/sisu/CHANGELOG_v5
@@ -38,6 +38,15 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_5.0.17.orig.tar.xz
   * use of language sub-dir for source sisu markup suited to permitting
     translation management by po4a
   * sisurc.yml minor
+  * Rakefile to help place sisu markup in a source language directory under po4a
+    management
+
+* Rakefile to assist in placing sisu markup under po4a management (sisu_manual)
+  * Provided as an example with sisu_manual
+  * fairly generic, but potentially dangerous, can be used to place sisu markup
+    source translations under po4a management, but user needs to know what this
+    is, (and how to set it up, hence sisu_manual as an example (despite the lack
+    of translations)) as can clobber/destroy files that are not managed by po4a.
 
 * minor cleaning
 
diff --git a/data/doc/sisu/markup-samples/sisu_manual/Rakefile b/data/doc/sisu/markup-samples/sisu_manual/Rakefile
new file mode 100644
index 00000000..1d9b5414
--- /dev/null
+++ b/data/doc/sisu/markup-samples/sisu_manual/Rakefile
@@ -0,0 +1,404 @@
+#!/usr/bin/env ruby
+raise 'Please, use ruby1.9.3 or later.' if RUBY_VERSION < '1.9.3'
+=begin
+ Common Rakefile, Rantfile to place sisu markup translation under
+ po4a management softlink Rakefile and Rantfile to this file
+
+ * Homepage: <http://www.jus.uio.no/sisu/SiSU>
+             <http://sisudoc.org>
+ * Download: <http://www.jus.uio.no/sisu/download>
+
+ Copyright (C) 2013 Ralph Amissah
+
+ * License: LGPL - GNU Lesser General Public License
+     [same license as Rant provided within the Rant package]
+
+ * Ralph Amissah <ralph@amissah.com>
+   Ralph Amissah <ralph.amissah@gmail.com>
+
+ Rake is a Ruby build program by Jim Weirich
+ * Rake may be downloaded and installed from:
+     <http://rake.rubyforge.org/>
+
+ Rant is a Ruby build program by Stefan Lang
+ * Rant may be downloaded and installed from:
+     <http://make.rubyforge.org/>
+
+ Notes on use:
+     rake -T
+   [if rant is preferred and installed]
+     rant -T
+=end
+require 'find'
+require 'fileutils'
+#require 'ftools'
+require 'rbconfig.rb'
+#include RbConfig
+require 'yaml'
+include FileUtils
+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}
+are managed by po4a, through translations of the source language to other languages.
+
+#{language.info_on_selection}
+    WOK
+  end
+  def rake_project
+    "Rakefile for placing #{name}"
+  end
+  self
+end
+def query
+  def answer?(ask)
+    resp='redo'
+    print ask + %{    ['yes', 'no' or 'quit']: }
+    resp=File.new('/dev/tty').gets.strip
+    if resp == 'yes';           true
+    elsif resp == 'no';         false
+    elsif resp =~/^quit|exit$/; exit
+    else
+      puts %{[please type: 'yes', 'no' or 'quit']}
+      answer?(ask)
+    end
+  end
+  self
+end
+def notice
+  def warn_and_proceed?
+    %{WARNING: This Software is used entirely at your own risk.
+    PROCEED?}
+  end
+  def default(selection=nil)
+    ans= if selection
+      case selection
+      when selection.is_a?(String)
+        <<-WOK
+  #{project_details.rake_project}
+    Information on alternative actions is available using: "rake help" or "rake -T"
+    Default action selected - "#{selection} #{project_details.name}"
+    #{warn_and_proceed?}
+        WOK
+      when :make
+        <<-WOK
+  #{project_details.rake_project}
+    Information on alternative actions is available using: "rake help" or "rake -T"
+    #{selection.upcase} selected - #{selection} #{project_details.name}
+    WARNING: this action assumes (and places) this project is under po4a
+    (translation) management. It will create the sub-directories:
+      #{language.translations_available_str}
+    & 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).
+    #{warn_and_proceed?}
+        WOK
+      when :clean
+        <<-WOK
+  #{project_details.rake_project}
+    Information on alternative actions is available using: "rake help" or "rake -T"
+    #{selection.upcase} selected - #{selection} #{project_details.name}
+    #{warn_and_proceed?}
+        WOK
+      when :distclean
+        <<-WOK
+  #{project_details.rake_project}
+    Information on alternative actions is available using: "rake help" or "rake -T"
+    #{selection.upcase} selected - #{selection} #{project_details.name}
+    WARNING: this action assumes (and places) this project is under po4a
+    (translation) management. It will remove the sub-directories:
+      #{language.translations_available_str}
+    & 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
+        <<-WOK
+  #{project_details.rake_project}
+    Information on alternative actions is available using: "rake help" or "rake -T"
+    #{selection.upcase} 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.translations_available_str}
+    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
+        <<-WOK
+  #{project_details.rake_project}
+    Information on alternative actions is available using: "rake help" or "rake -T"
+    Default action selected - "#{selection} #{project_details.name}"
+    #{warn_and_proceed?}
+        WOK
+      end
+    else
+      <<-WOK
+  #{project_details.rake_project}
+    Information on alternative actions is available using: "rake help" or "rake -T"
+    Default action selected - "install and to setup #{project_details.name}"
+    #{warn_and_proceed?}
+      WOK
+    end
+    resp=query.answer?(ans)
+    exit unless resp
+  end
+  def project_help
+    puts <<-WOK
+#{project_details.name}
+#{project_details.rake_project}
+
+This rake file is 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}
+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:  #{translations_selected_str}
+The languages selected are located in the file: #{filename.languages}
+
+sisu available language list: #{sisu_available_str}
+
+For a more detailed and up to date task list use:
+
+  rake -T
+
+  WOK
+  end
+  self
+end
+def tasks
+  system('rake -T')
+end
+def filename
+  def languages
+    'translation_languages'
+  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 language
+  def source #source_language
+    'en'
+  end
+  def translations_selected #translation_languages
+    IO.read(filename.languages, mode: 'r:utf-8').split(/\s+/)
+  end
+  def translations_available
+    translations_selected & sisu_available
+  end
+  def info_on_selection
+    if translations_selected != translations_available
+      <<-WOK
+WARNING: language selections mismatch
+
+The current language translation selection appears to be: #{translations_selected_str}
+Of which the following are valid (available) selections:  #{translations_available_str}
+
+sisu available language list: #{sisu_available_str}
+
+the following will be used: #{translations_available_str}
+The languages selected are located in the file:    #{filename.languages}
+      WOK
+    else
+      <<-WOK
+The current language translation selection is:  #{translations_selected_str}
+The languages selected are located in the file: #{filename.languages}
+
+sisu available language list: #{sisu_available_str}
+      WOK
+    end
+  end
+  def sisu_available
+    %w[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]
+  end
+  def translations_selected_str
+    language.translations_selected.join(' ')
+  end
+  def translations_available_str
+    language.translations_available.join(' ')
+  end
+  def sisu_available_str
+    language.sisu_available.join(' ')
+  end
+  self
+end
+def files_src
+  def ssm
+    Dir.glob("#{language.source}/*.ssm").sort
+  end
+  def sst
+    Dir.glob("#{language.source}/*.sst").sort
+  end
+  def ssi
+    Dir.glob("#{language.source}/*.ssi").sort
+  end
+  def all
+    Dir.glob("#{language.source}/*{.ssm,.sst,.ssi}").sort
+  end
+  self
+end
+def po4a_cfg_file
+  File.open("#{Dir.pwd}/#{filename.po4a_cfg}",'w')
+end
+def po4a
+  def configure #po4a_cfg
+    po4a_cfg_arr=[]
+    po4a_cfg_arr << "[po4a_langs] #{language.translations_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}\//,'')
+      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}\//,'')
+      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}\//,'')
+      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
+  	system("po4a --keep 0 --no-backups --package-name sisu-manual #{po4a_flags.normal} #{filename.po4a_cfg}")
+  end
+  self
+end
+def project
+  dir_mk(dir.pot)
+  language.translations_available.each do |lang_dir|
+    dir_lang="#{Dir.pwd}/#{dir.po}/#{lang_dir}"
+    dir_mk(dir_lang)
+  end
+  po4a.configure
+end
+def clean
+	#rm -rf ../build
+  FileUtils.rm_f Dir.glob("#{dir.po}/*/*.po~")
+end
+def distclean
+  FileUtils::rm_f(filename.po4a_cfg)
+  FileUtils::rm_r(language.translations_available,:force => true)
+end
+
+#% task lists
+desc "runs make (see its description below)"
+task :default => [:make]
+desc "assist with having sisu markup files managed by po4a
+                   create configuration files, and language directories and
+                   populate them with po4a pot & po files for translation and
+                   from those (as translated) create translated sisu markup
+                   .ssm .sst & .ssi files in corresponding language sub-directories"
+task :make => [:notice_make_,:build_]
+desc "help"
+task :help => [:project_help_,:tasks_]
+desc "clean temporary files"
+task :clean => [:notice_clean_,:clean_]
+desc "removes auto-generated files under po4a management
+                  including translated .ssm .sst & .ssi files,
+                  that are created from po4a pot and po files"
+task :distclean => [:notice_distclean_,:distclean_]
+desc "runs 'distclean' and 'make' (see their descriptions above)"
+task :rebuild => [:notice_rebuild_,:distclean_,:build_]
+if File.directory?(dir.pot) \
+and File.directory?(dir.po)
+  #desc ""
+  task :clean! => [:clean_]
+  task :distclean! => [:distclean_]
+  task :rebuild! => [:distclean_,:build_]
+  task :make! => [:build_]
+else
+  task :make! => [:build_]
+end
+
+#% task actions
+task :project_help_ do
+  notice.project_help
+end
+task :tasks_ do
+  tasks
+end
+task :build_ do
+  project
+end
+task :clean_ do
+  clean
+end
+task :distclean_ do
+  distclean
+end
+task :notice_default_ do
+  notice.default
+end
+task :notice_make_ do
+  notice.default(:make)
+end
+task :notice_clean_ do
+  notice.default(:clean)
+end
+task :notice_distclean_ do
+  notice.default(:distclean)
+end
+task :notice_rebuild_ do
+  notice.default(:rebuild)
+end
+__END__
diff --git a/data/doc/sisu/markup-samples/sisu_manual/translation_languages b/data/doc/sisu/markup-samples/sisu_manual/translation_languages
new file mode 100644
index 00000000..d84a94e8
--- /dev/null
+++ b/data/doc/sisu/markup-samples/sisu_manual/translation_languages
@@ -0,0 +1 @@
+de fr es ja ru zh