root: created srcBOOK for PDF document creation

Since we want an offline capable PDF documentation with CI
quality maintenances, we should develop a new srcBOOK/ pipeline
for it. Hence, let's re-use libreoffice and implementations from
srcRESEARCH/ directory.

This patch creates srcBOOK/ for PDF document creation in root
repository.

Co-authored-by: Shuralyov, Jean <[email protected]>
Co-authored-by: Galyna, Cory <[email protected]>
Co-authored-by: (Holloway) Chew, Kean Ho <[email protected]>
Signed-off-by: (Holloway) Chew, Kean Ho <[email protected]>

CONFIG.toml

@@ -228,6 +228,22 @@ PROJECT_ANGULAR = ''
 
 
 
+######################
+# BOOK TECHNOLOGY    #
+######################
+# PROJECT_BOOK
+# This is the control variable used for enabling e-book generation and also
+# defining its source directory relative to PROJECT_PATH_ROOT. Depending on
+# the offered service (e.g. GitHub Actions), setting this variable with value
+# shall notify the CI provider to setup the necessary software automatically.
+#
+# To enable it: simply supply the path (e.g. default is 'srcBOOK').
+# To disable it: simply supply an empty path (e.g. default is '').
+PROJECT_BOOK = 'srcBOOK'
+
+
+
+
 ######################
 # C TECHNOLOGY       #
 ######################
@@ -452,6 +468,7 @@ GOOGLEAI_BLOCK_HARASSMENT = 'BLOCK_NONE'
 # Do note that should the following technologies are enabled, LibreOffice shall
 # be installed regardless of this control variable:
 #     (1) PROJECT_RESEARCH - using Libreoffice by default.
+#     (2) PROJECT_BOOK - using Libreoffice by default.
 #
 # To enable it: simply supply the path (e.g. default is 'srcLIBREOFFICE').
 # To disable it: simply supply an empty path (e.g. default is '').

automataCI/common_unix-any.sh

@@ -86,6 +86,12 @@ if [ $? -ne 0 ]; then
 fi
 
 
+Run_Subroutine_Exec "$PROJECT_BOOK" "BOOK"
+if [ $? -ne 0 ]; then
+        return 1
+fi
+
+
 Run_Subroutine_Exec "$PROJECT_C" "C"
 if [ $? -ne 0 ]; then
         return 1

automataCI/common_windows-any.ps1

@@ -83,6 +83,11 @@ if ($___process -ne 0) {
 	return 1
 }
 
+$___process = RUN-Subroutine-Exec "${env:PROJECT_BOOK}" "BOOK"
+if ($___process -ne 0) {
+	return 1
+}
+
 $___process = RUN-Subroutine-Exec "${env:PROJECT_C}" "C"
 if ($___process -ne 0) {
 	return 1

automataCI/env_unix-any.sh

@@ -182,6 +182,7 @@ fi
 
 
 if [ $(STRINGS_Is_Empty "$PROJECT_LIBREOFFICE") -ne 0 ] ||
+        [ $(STRINGS_Is_Empty "$PROJECT_BOOK") -ne 0 ] ||
         [ $(STRINGS_Is_Empty "$PROJECT_RESEARCH") -ne 0 ]; then
         I18N_Install "LIBREOFFICE"
         LIBREOFFICE_Setup

automataCI/env_windows-any.ps1

@@ -156,6 +156,7 @@ if ($(STRINGS-Is-Empty "${env:PROJECT_ANGULAR}") -ne 0) {
 
 
 if (($(STRINGS-Is-Empty "${env:PROJECT_LIBREOFFICE}") -ne 0) -or
+	($(STRINGS-Is-Empty "${env:PROJECT_BOOK}") -ne 0) -or
 	($(STRINGS-Is-Empty "${env:PROJECT_RESEARCH}") -ne 0)) {
 	$null = I18N-Install "LIBREOFFICE"
 	if ($(LIBREOFFICE-Setup) -ne 0) {

srcBOOK/.ci/build_unix-any.sh

@@ -0,0 +1,106 @@
+#!/bin/sh
+# Copyright 2024 (Holloway) Chew, Kean Ho <[email protected]>
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at:
+#                 http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+
+
+
+# initialize
+if [ "$PROJECT_PATH_ROOT" = "" ]; then
+        >&2 printf "[ ERROR ] - Please run from automataCI/ci.sh.ps1 instead!\n"
+        return 1
+fi
+
+. "${LIBS_AUTOMATACI}/services/io/fs.sh"
+. "${LIBS_AUTOMATACI}/services/i18n/translations.sh"
+. "${LIBS_AUTOMATACI}/services/compilers/libreoffice.sh"
+
+
+
+
+# execute
+I18N_Activate_Environment
+LIBREOFFICE_Is_Available
+if [ $? -ne 0 ]; then
+        I18N_Activate_Failed
+        return 1
+fi
+
+
+
+
+# setup inportant variables
+___name="${PROJECT_SKU}_${PROJECT_VERSION}_any-any"
+___source="book.odt"
+
+
+
+
+# build PDF
+___source="${PROJECT_PATH_ROOT}/${PROJECT_BOOK}/${___source}"
+___dest="${PROJECT_PATH_ROOT}/${PROJECT_PATH_TEMP}/build-${___name}"
+I18N_Prepare "$___source"
+FS_Is_File "$___source"
+if [ $? -ne 0 ]; then
+        I18N_Prepare_Failed
+        return 1
+fi
+
+FS_Remake_Directory "$___dest"
+
+## IMPORTANT: refer the following page for modifying parameters:
+##   https://help.libreoffice.org/latest/en-US/text/shared/guide/pdf_params.html
+I18N_Build "$___source"
+$(LIBREOFFICE_Get) --headless --convert-to "pdf:writer_pdf_Export:{
+        \"UseLosslessCompression\": true,
+        \"Quality\": 100,
+        \"SelectPdfVersion\": 0,
+        \"PDFUACompliance\": false,
+        \"UseTaggedPDF\": true,
+        \"ExportFormFields\": true,
+        \"FormsType\": 1,
+        \"ExportBookmarks\": true,
+        \"ExportPlaceholders\": true
+}" --outdir "$___dest" "$___source"
+___process=$?
+if [ $___process -ne 0 ]; then
+        I18N_Build_Failed
+        return 1
+fi
+
+
+
+
+## export output
+___source="${___dest}/$(FS_Get_File "$___source")"
+___source="$(FS_Extension_Replace "$___source" ".odt" ".pdf")"
+___dest="${PROJECT_PATH_ROOT}/${PROJECT_PATH_BUILD}/${___name}.pdf"
+
+FS_Is_File "$___source"
+if [ $? -ne 0 ]; then
+        I18N_Build_Failed
+        return 1
+fi
+
+I18N_Export "$___dest"
+FS_Remove_Silently "$___dest"
+FS_Copy_File "$___source" "$___dest"
+if [ $? -ne 0 ]; then
+        I18N_Export_Failed
+        return 1
+fi
+
+
+
+
+# report status
+return 0

srcBOOK/.ci/build_windows-any.ps1

@@ -0,0 +1,105 @@
+# Copyright 2024 (Holloway) Chew, Kean Ho <[email protected]>
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy
+# of the License at:
+#                 http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+
+
+
+# initialize
+if (-not (Test-Path -Path $env:PROJECT_PATH_ROOT)) {
+	Write-Error "[ ERROR ] - Please run from automataCI\ci.sh.ps1 instead!`n"
+	return 1
+}
+
+. "${env:LIBS_AUTOMATACI}\services\io\fs.ps1"
+. "${env:LIBS_AUTOMATACI}\services\i18n\translations.ps1"
+. "${env:LIBS_AUTOMATACI}\services\compilers\libreoffice.ps1"
+
+
+
+
+# execute
+$null = I18N-Activate-Environment
+$___process = LIBREOFFICE-Is-Available
+if ($___process -ne 0) {
+	$null = I18N-Activate-Failed
+	return 1
+}
+
+
+
+
+# setup important variables
+$___name = "${env:PROJECT_SKU}_${env:PROJECT_VERSION}_any-any"
+$___source = "book.odt"
+
+
+
+
+# build PDF
+$___source = "${env:PROJECT_PATH_ROOT}\${env:PROJECT_BOOK}\${___source}"
+$___dest = "${env:PROJECT_PATH_ROOT}\${env:PROJECT_PATH_TEMP}\build-${___name}"
+$null = I18N-Prepare "${___source}"
+$___process = FS-Is-File "${___source}"
+if ($___process -ne 0) {
+	$null = I18N-Prepare-Failed
+	return 1
+}
+$null = FS-Remake-Directory "${___dest}"
+
+## IMPORTANT: refer the following page for modifying parameters:
+##   https://help.libreoffice.org/latest/en-US/text/shared/guide/pdf_params.html
+$null = I18N-Build "${___source}"
+$___process = OS-Exec "$(LIBREOFFICE-Get)" @"
+--headless --convert-to "pdf:writer_pdf_Export:{
+	"UseLosslessCompression": true,
+	"Quality": 100,
+	"SelectPdfVersion": 0,
+	"PDFUACompliance": false,
+	"UseTaggedPDF": true,
+	"ExportFormFields": true,
+	"FormsType": 1,
+	"ExportBookmarks": true,
+	"ExportPlaceholders": true,
+}" --outdir "${___dest}" "${___source}"
+"@
+if ($___process -ne 0) {
+	$null = I18N-Build-Failed
+	return 1
+}
+
+
+
+
+# export output
+$___source = "${___dest}\$(FS-Get-File "${___source}")"
+$___source = FS-Extension-Replace "${___source}" ".odt" ".pdf"
+$___dest = "${env:PROJECT_PATH_ROOT}\${env:PROJECT_PATH_BUILD}\${___name}.pdf"
+
+$___process = FS-Is-File "${___source}"
+if ($___process -ne 0) {
+	$null = I18N-Build-Failed
+	return 1
+}
+
+$null = I18N-Export "${___dest}"
+$null = FS-Remove-Silently "${___dest}"
+$___process = FS-Copy-File "${___source}" "${___dest}"
+if ($___process -ne 0) {
+	$null = I18N-Export-Failed
+	return 1
+}
+
+
+
+
+# report status
+return 0