improve doc build toolchain to use latest phpdocumentor; one fix to the manual

diff --git a/.gitignore b/.gitignore
index 9eb7cb7..420d138 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -2,7 +2,11 @@
 /.idea
 /doc/api
 /doc/build/.phpdoc
+/doc/build/.phive
 /doc/build/composer.lock
+/doc/build/docbook-xsl
+/doc/build/phive
+/doc/build/phpDocumentor
 /doc/build/vendor
 /doc/manual/phpxmlrpc_manual.html
 /doc/manual/phpxmlrpc_manual.pdf

diff --git a/doc/build/composer.json b/doc/build/composer.json
index 64b8c47..cec1671 100644 (file)
--- a/doc/build/composer.json
+++ b/doc/build/composer.json
@@ -7,6 +7,8 @@
         "docbook/docbook-xsl": "^1.79",
         "phpdocumentor/phpdocumentor": "^2.9.1 || ^3.1.2"
     },
+    "minimum-stability": "dev",
+    "prefer-stable": true,
     "repositories": [
         {
             "type": "package",

diff --git a/doc/build/convert.php b/doc/build/convert.php
index 96c1730..2ca35fe 100644 (file)
--- a/doc/build/convert.php
+++ b/doc/build/convert.php
@@ -14,6 +14,7 @@ if ($_SERVER['argc'] < 4) {
 $doc = $_SERVER['argv'][1];
 $xss = $_SERVER['argv'][2];
 $target = $_SERVER['argv'][3];
+$docbookDir = isset($_SERVER['argv'][4]) ? $_SERVER['argv'][4] : './build/vendor/docbook/docbook-xsl';
 
 if (!file_exists($doc))
   error("KO: file $doc cannot be found");
@@ -23,8 +24,8 @@ if (!file_exists($xss))
 info("Starting xsl conversion process...");
 
 // Replace tokens in the existing xslt file
-$docbookFoXslPath = realpath('./build/vendor/docbook/docbook-xsl/fo/docbook.xsl');
-$docbookChunkXslPath = realpath('./build/vendor/docbook/docbook-xsl/xhtml/chunk.xsl');
+$docbookFoXslPath = realpath($docbookDir.'/fo/docbook.xsl');
+$docbookChunkXslPath = realpath($docbookDir.'/xhtml/chunk.xsl');
 file_put_contents(
     $xss,
     str_replace(

diff --git a/doc/build/generate.sh b/doc/build/generate.sh
index f15b7dc..179c2ac 100755 (executable)
--- a/doc/build/generate.sh
+++ b/doc/build/generate.sh
@@ -2,11 +2,16 @@
 
 set -e
 
-cd "$(dirname -- "$(dirname -- "${BASH_SOURCE[0]}")")"
+cd "$(dirname -- "$(dirname -- "$(realpath "${BASH_SOURCE[0]}")")")"
+
+PHPDOC='./build/phpDocumentor'
+DOCBOOKXSLTDIR='./build/docbook-xsl'
+#PHPDOC='php ./build/vendor/bin/phpdoc'
+#DOCBOOKXSLTDIR='./build/vendor/docbook/docbook-xsl'
 
 ### API docs
 
-php ./build/vendor/bin/phpdoc run --cache-folder './build/.phpdoc' -d "$(realpath ../src/)" -t './api' --title PHPXMLRPC --defaultpackagename PHPXMLRPC
+$PHPDOC run --cache-folder './build/.phpdoc' -d "$(realpath ../src/)" -t './api' --title PHPXMLRPC --defaultpackagename PHPXMLRPC
 
 ### User Manual
 
@@ -18,6 +23,6 @@ php ./build/vendor/bin/phpdoc run --cache-folder './build/.phpdoc' -d "$(realpat
 # PDF file from asciidoc via docbook and apache fop
 # @todo test: is it faster to use pandoc+texlive (including tools download time)? Does it render better?
 asciidoctor -d book -b docbook -o './build/phpxmlrpc_manual.xml' './manual/phpxmlrpc_manual.adoc'
-php ./build/convert.php './build/phpxmlrpc_manual.xml' './build/custom.fo.xsl' './manual/phpxmlrpc_manual.fo.xml'
+php ./build/convert.php './build/phpxmlrpc_manual.xml' './build/custom.fo.xsl' './manual/phpxmlrpc_manual.fo.xml' "$DOCBOOKXSLTDIR"
 fop ./manual/phpxmlrpc_manual.fo.xml ./manual/phpxmlrpc_manual.pdf
 rm ./build/phpxmlrpc_manual.xml ./manual/phpxmlrpc_manual.fo.xml

diff --git a/doc/build/setup_tools.sh b/doc/build/setup_tools.sh
old mode 100644 (file)
new mode 100755 (executable)
index c4aa14a..0339a91
--- a/doc/build/setup_tools.sh
+++ b/doc/build/setup_tools.sh
@@ -8,15 +8,43 @@ sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
     asciidoctor fop git unzip zip
 
 PHPPKG=$(dpkg --list | grep php | grep cli | grep -v -F '(default)' | awk '{print $2}')
-sudo DEBIAN_FRONTEND=noninteractive apt-get install -y "${PHPPKG/cli/xsl}"
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
+    asciidoctor \
+    curl \
+    gpg \
+    "${PHPPKG}" \
+    "${PHPPKG/cli/xsl}" \
+    unzip
 
 cd "$(dirname -- "${BASH_SOURCE[0]}")"
-# in case we are switching between php versions, always reinstall every tool with the correct version...
-if [ -f composer.lock ]; then
-    rm composer.lock
-fi
-composer install --no-dev
-#sudo chown -R "$(id -u):$(id -g)" vendor
 
+# Install phpdocumentor and the docbook xslt using Composer
+# Sadly this method, as of 2023/1, does not allow installing version 3.3.0 and later
+## in case we are switching between php versions, always reinstall every tool with the correct version...
+#if [ -f composer.lock ]; then
+#    rm composer.lock
+#fi
+#composer install --no-dev
 # required as of phpdoc 3.1.2
-sed -r -i -e "s|resource: '%kernel\\.project_dir%/vendor/phpdocumentor/reflection/src/phpDocumentor/Reflection/Php'|resource: '%kernel.project_dir%/../reflection/src/phpDocumentor/Reflection/Php'|g" ./vendor/phpdocumentor/phpdocumentor/config/reflection.yaml
+#sed -r -i -e "s|resource: '%kernel\\.project_dir%/vendor/phpdocumentor/reflection/src/phpDocumentor/Reflection/Php'|resource: '%kernel.project_dir%/../reflection/src/phpDocumentor/Reflection/Php'|g" ./vendor/phpdocumentor/phpdocumentor/config/reflection.yaml
+#sudo chown -R "$(id -u):$(id -g)" vendor
+
+# Install the DocBook xslt
+if [ ! -d docbook-xsl ]; then
+    curl -fsSL -o dbx.zip "https://github.com/docbook/xslt10-stylesheets/releases/download/release/1.79.2/docbook-xsl-1.79.2.zip"
+    unzip dbx.zip
+    mv docbook-xsl-1.79.2 docbook-xsl
+    rm dbx.zip
+fi
+
+# Install phpdocumentor via Phive
+# @todo wouldn't it be quicker to just scan the github page for the last release and just get the phar?
+curl -fsSL -o phive "https://phar.io/releases/phive.phar"
+#curl -fsSL -o -O phive.phar.asc "https://phar.io/releases/phive.phar.asc"
+#gpg --keyserver hkps://keys.openpgp.org --recv-keys 0x6AF725270AB81E04D79442549D8A98B29B2D5D79
+#gpg --verify phive.phar.asc phive.phar
+#rm phive.phar.asc
+chmod +x phive
+./phive install --trust-gpg-keys F33A0AF69AF7A8B15017DB526DA3ACC4991FFAE5 -t "$(pwd)" phpdocumentor
+
+#sudo chown -R "$(id -u):$(id -g)" vendor

diff --git a/doc/manual/phpxmlrpc_manual.adoc b/doc/manual/phpxmlrpc_manual.adoc
index a7a1519..68d3d10 100644 (file)
--- a/doc/manual/phpxmlrpc_manual.adoc
+++ b/doc/manual/phpxmlrpc_manual.adoc
@@ -1144,8 +1144,8 @@ to trigger execution of uncontrolled PHP code on your server, opening the door t
 enable this option when you trust completely the remote server/client. DO NOT USE THIS WITH UNTRUSTED USER INPUT
 
 Note also that there are multiple limitations to this: the same PHP class definition must be available on both ends of
-the communication; the class constructor will be called but with no parameters at all, and methods such as `__unserialize`
-or `__wakeup` will not be called. Also, if a different toolkit than the phpxmlrpc library is used on the receiving side,
+the communication; the class constructor will be called but with no parameters at all, and methods such as `+__unserialize+`
+or `+__wakeup+` will not be called. Also, if a different toolkit than the phpxmlrpc library is used on the receiving side,
 it might reject the generated xml as invalid.
 
 === Code generation, Proxy objects & co.