From e8456e77a0f50b0ed2b81ac8ff807bc64862b777 Mon Sep 17 00:00:00 2001 From: gggeek Date: Thu, 5 Jan 2023 23:11:15 +0000 Subject: [PATCH] one more revamp of the doc gen toolchain --- .gitignore | 4 +- doc/build/composer.json | 30 ------------ doc/build/convert.php | 98 ------------------------------------- doc/build/custom.fo.xsl | 102 --------------------------------------- doc/build/custom.xsl | 91 ---------------------------------- doc/build/generate.sh | 14 ++++-- doc/build/setup_tools.sh | 30 ++++++++---- 7 files changed, 32 insertions(+), 337 deletions(-) delete mode 100644 doc/build/composer.json delete mode 100644 doc/build/convert.php delete mode 100644 doc/build/custom.fo.xsl delete mode 100644 doc/build/custom.xsl diff --git a/.gitignore b/.gitignore index 420d1383..8b226248 100644 --- a/.gitignore +++ b/.gitignore @@ -3,11 +3,11 @@ /doc/api /doc/build/.phpdoc /doc/build/.phive -/doc/build/composer.lock /doc/build/docbook-xsl +/doc/build/eisvogel.latex +/doc/build/images /doc/build/phive /doc/build/phpDocumentor -/doc/build/vendor /doc/manual/phpxmlrpc_manual.html /doc/manual/phpxmlrpc_manual.pdf /vendor/* diff --git a/doc/build/composer.json b/doc/build/composer.json deleted file mode 100644 index cec16710..00000000 --- a/doc/build/composer.json +++ /dev/null @@ -1,30 +0,0 @@ -{ - "name": "phpxmlrpc/phpxmlrpc-doc-toolchain", - "require": { - "php": "^5.3.0 || ^7.0 || ^8.0", - "ext-dom": "*", - "ext-xsl": "*", - "docbook/docbook-xsl": "^1.79", - "phpdocumentor/phpdocumentor": "^2.9.1 || ^3.1.2" - }, - "minimum-stability": "dev", - "prefer-stable": true, - "repositories": [ - { - "type": "package", - "package": { - "name": "docbook/docbook-xsl", - "version": "1.79.2", - "dist": { - "url": "https://github.com/docbook/xslt10-stylesheets/releases/download/release/1.79.2/docbook-xsl-1.79.2.zip", - "type": "zip" - } - } - } - ], - "config": { - "allow-plugins": { - "symfony/flex": true - } - } -} diff --git a/doc/build/convert.php b/doc/build/convert.php deleted file mode 100644 index 2ca35fe9..00000000 --- a/doc/build/convert.php +++ /dev/null @@ -1,98 +0,0 @@ -load($doc); -$xsl = new DOMDocument; -$xsl->load($xss); - -// Configure the transformer -$processor = new XSLTProcessor; -if (version_compare(PHP_VERSION, '5.4', "<")) { - if (defined('XSL_SECPREF_WRITE_FILE')) { - ini_set("xsl.security_prefs", XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); - } -} else { - // the php online docs only mention setSecurityPrefs, but somehow some installs have setSecurityPreferences... - if (method_exists('XSLTProcessor', 'setSecurityPrefs')) { - $processor->setSecurityPrefs(XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); - } else { - $processor->setSecurityPreferences(XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE); - } -} -if (is_dir($target)) { - if (!$processor->setParameter('', 'base.dir', $target)) { - error("KO setting param base.dir"); - } -} - -// attach the xsl rules -$processor->importStyleSheet($xsl); - -$out = $processor->transformToXML($xml); - -// bring back the xsl file to its pristine state -file_put_contents( - $xss, - str_replace( - array($docbookFoXslPath, $docbookChunkXslPath), - array('%fo-docbook.xsl%', '%docbook-chunk.xsl%'), - file_get_contents($xss) - ) -); - -if (!is_dir($target)) { - if (!file_put_contents($target, $out)) { - error("KO saving output to '{$target}'"); - } -} - -info("OK"); - -// *** functions *** - -function info($msg) -{ - echo "$msg\n"; -} - -function error($msg, $errcode = 1) -{ - fwrite(STDERR, "$msg\n"); - exit($errcode); -} diff --git a/doc/build/custom.fo.xsl b/doc/build/custom.fo.xsl deleted file mode 100644 index 2f37de68..00000000 --- a/doc/build/custom.fo.xsl +++ /dev/null @@ -1,102 +0,0 @@ - - - - - - - - - - -1 -no -ansi -0 -1 -php -A4 -1 - - - 80% - - - - - - - - - - - - - - - - - - - - - - - - - - - ( void ) - - - ( ) - - - - - - ( ... ) - - - - - - - ( - - - - - - - - - - - , - - - ) - - - - - - - - - - - - = - - - - - diff --git a/doc/build/custom.xsl b/doc/build/custom.xsl deleted file mode 100644 index a76d100a..00000000 --- a/doc/build/custom.xsl +++ /dev/null @@ -1,91 +0,0 @@ - - - - - - - - - - -no -ansi -xmlrpc.css -0 - - - - - - - - - - ( - - - - - - - - - - - - void ) - - - - ... - ) - - - - - - - , - - - ) - - - - - - - - - - - - - - - - - - - - - - - - = - - - - - diff --git a/doc/build/generate.sh b/doc/build/generate.sh index 179c2acc..337e3047 100755 --- a/doc/build/generate.sh +++ b/doc/build/generate.sh @@ -20,9 +20,13 @@ $PHPDOC run --cache-folder './build/.phpdoc' -d "$(realpath ../src/)" -t './api' # solution is preferred #asciidoctor -d book -o './manual/phpxmlrpc_manual.html' './manual/phpxmlrpc_manual.adoc' -# 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? +# PDF file from asciidoc +# 1. get docbook 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' "$DOCBOOKXSLTDIR" -fop ./manual/phpxmlrpc_manual.fo.xml ./manual/phpxmlrpc_manual.pdf -rm ./build/phpxmlrpc_manual.xml ./manual/phpxmlrpc_manual.fo.xml +# 2a. then PDF via apache fop +#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 ./manual/phpxmlrpc_manual.fo.xml +# 2b. then PDF via pandoc+xelatex, using a nice template +cd build; pandoc -s --from=docbook --pdf-engine=xelatex --data-dir=. --template=eisvogel -o ../manual/phpxmlrpc_manual.pdf phpxmlrpc_manual.xml; cd .. +rm ./build/phpxmlrpc_manual.xml diff --git a/doc/build/setup_tools.sh b/doc/build/setup_tools.sh index 0339a91a..ee08bcb5 100755 --- a/doc/build/setup_tools.sh +++ b/doc/build/setup_tools.sh @@ -4,17 +4,17 @@ set -e -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}') + +# git, curl, gpg are needed by phive, used to install phpdocumentor +# @todo besides php-cli, there are other php extensions used by phpdocumentor that we should make sure are onboard sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \ - asciidoctor \ - curl \ - gpg \ - "${PHPPKG}" \ - "${PHPPKG/cli/xsl}" \ - unzip + asciidoctor curl git gpg unzip zip "${PHPPKG}" \ + pandoc texlive-xetex texlive-fonts-extra texlive-latex-extra + +#sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \ +# fop \ +# "${PHPPKG/cli/xsl}" \ cd "$(dirname -- "${BASH_SOURCE[0]}")" @@ -37,6 +37,18 @@ if [ ! -d docbook-xsl ]; then rm dbx.zip fi +# Get the eisvogel template for pandoc +if [ ! -f eisvogel.latex ]; then + curl -fsSL -o ev.zip "https://github.com/Wandmalfarbe/pandoc-latex-template/releases/download/v2.1.0/Eisvogel-2.1.0.zip" + unzip ev.zip + rm -rf examples + rm ev.zip LICENSE CHANGELOG.md icon.png +fi + +if [ ! -L images ]; then + ln -s "$(realpath ../manual/images)" images +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" -- 2.47.0