root: added srcBOOK pipeline feature

Since there is a way to reliably produce a high-grade PDF book
using LibreOffice, it's best we develop its pipeline for
consistencies and version control production capability. Hence,
let's do this.

This patch adds srcBOOk pipeline feature into 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       #
 ######################

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,117 @@
+#!/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 important variables
+Build_Book() {
+        #___input="$1"
+        #___name="$2"
+
+        # build PDF
+        ___source="${PROJECT_PATH_ROOT}/${PROJECT_BOOK}/${1}"
+        ___dest="${PROJECT_PATH_ROOT}/${PROJECT_PATH_TEMP}/build-${2}"
+        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}/${2}.pdf"
+
+        FS_Is_File "$___source"
+        if [ $? -ne 0 ]; then
+                I18N_Build_Failed
+                return 1
+        fi
+
+        I18N_Export "$___dest"
+        FS_Remove_Silently "$___dest"
+        FS_Make_Housing_Directory "$___dest"
+        FS_Copy_File "$___source" "$___dest"
+        if [ $? -ne 0 ]; then
+                I18N_Export_Failed
+                return 1
+        fi
+
+
+        # report status
+        return 0
+}
+
+
+
+
+# build books
+Build_Book "en.odt" "${PROJECT_SKU}_${PROJECT_VERSION}_en_any-any"
+if [ $? -ne 0 ]; then
+        return 1
+fi
+
+
+
+
+# report status
+return 0

srcBOOK/.ci/build_windows-any.ps1

@@ -0,0 +1,120 @@
+# 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
+function Build-Book {
+	param(
+		[string]$___input,
+		[string]$___name
+	)
+
+
+	# build PDF
+	$___source = "${env:PROJECT_PATH_ROOT}\${env:PROJECT_BOOK}\${___input}"
+	$___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}"
+	$null = FS-Make-Housing-Directory "${___dest}"
+	$___process = FS-Copy-File "${___source}" "${___dest}"
+	if ($___process -ne 0) {
+		$null = I18N-Export-Failed
+		return 1
+	}
+
+
+	# report status
+	return 0
+}
+
+
+
+
+# build books
+$___process = Build-Book "en.odt" "${env:PROJECT_SKU}_${env:PROJECT_VERSION}_en_any-any"
+if ($___process -ne 0) {
+	return 1
+}
+
+
+
+
+# report status
+return 0