From: gggeek <giunta.gaetano@gmail.com>
Date: Thu, 5 Jan 2023 23:11:15 +0000 (+0000)
Subject: one more revamp of the doc gen toolchain
X-Git-Tag: 4.9.4~22
X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=e8456e77a0f50b0ed2b81ac8ff807bc64862b777;p=plcapi.git
one more revamp of the doc gen toolchain
---
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 @@
-<?php
-/**
- * Script used to convert docbook source to human-readable docs
- *
- * @copyright (c) 2007-2023 G. Giunta
- *
- * @todo rename to something akin to xsltproc
- */
-
-if ($_SERVER['argc'] < 4) {
- error("Usage: php convert.php docbook.xml stylesheet.xsl output-dir|output_file");
-}
-
-$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");
-if (!file_exists($xss))
- error("KO: file $xss cannot be found");
-
-info("Starting xsl conversion process...");
-
-// Replace tokens in the existing xslt file
-$docbookFoXslPath = realpath($docbookDir.'/fo/docbook.xsl');
-$docbookChunkXslPath = realpath($docbookDir.'/xhtml/chunk.xsl');
-file_put_contents(
- $xss,
- str_replace(
- array('%fo-docbook.xsl%', '%docbook-chunk.xsl%'),
- array($docbookFoXslPath, $docbookChunkXslPath),
- file_get_contents($xss)
- )
-);
-
-// Load the XML source
-$xml = new DOMDocument;
-$xml->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 @@
-<?xml version='1.0'?>
-<xsl:stylesheet
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
- xmlns:fo="http://www.w3.org/1999/XSL/Format">
-<!--
- Customization xsl stylesheet for docbook to pdf transform
- @author Gaetano Giunta
- @copyright (c) 2007-2015 G. Giunta
- @license code licensed under the BSD License
--->
-
-
-<!-- import base stylesheet. This assumes the xslt is preprocessed before being used -->
-<xsl:import href="%fo-docbook.xsl%"/>
-
-
-<!-- customization vars -->
-<xsl:param name="fop1.extensions">1</xsl:param>
-<xsl:param name="draft.mode">no</xsl:param>
-<xsl:param name="funcsynopsis.style">ansi</xsl:param>
-<xsl:param name="id.warnings">0</xsl:param>
-<xsl:param name="highlight.source">1</xsl:param>
-<xsl:param name="highlight.default.language">php</xsl:param>
-<xsl:param name="paper.type">A4</xsl:param>
-<xsl:param name="shade.verbatim">1</xsl:param>
-
-<xsl:attribute-set name="verbatim.properties">
- <xsl:attribute name="font-size">80%</xsl:attribute>
-</xsl:attribute-set>
-
-
-<!-- elements added / modified -->
-<xsl:template match="funcdef/function">
- <xsl:choose>
- <xsl:when test="$funcsynopsis.decoration != 0">
- <fo:inline font-weight="bold">
- <xsl:apply-templates/>
- </fo:inline>
- </xsl:when>
- <xsl:otherwise>
- <xsl:apply-templates/>
- </xsl:otherwise>
- </xsl:choose>
- <xsl:text> </xsl:text>
-</xsl:template>
-
-<xsl:template match="funcdef/type">
- <xsl:apply-templates/>
- <xsl:text> </xsl:text>
-</xsl:template>
-
-<xsl:template match="void">
- <xsl:choose>
- <xsl:when test="$funcsynopsis.style='ansi'">
- <xsl:text>( void )</xsl:text>
- </xsl:when>
- <xsl:otherwise>
- <xsl:text>( )</xsl:text>
- </xsl:otherwise>
- </xsl:choose>
-</xsl:template>
-
-<xsl:template match="varargs">
- <xsl:text>( ... )</xsl:text>
-</xsl:template>
-
-<xsl:template match="paramdef">
- <xsl:variable name="paramnum">
- <xsl:number count="paramdef" format="1"/>
- </xsl:variable>
- <xsl:if test="$paramnum=1">( </xsl:if>
- <xsl:choose>
- <xsl:when test="$funcsynopsis.style='ansi'">
- <xsl:apply-templates/>
- </xsl:when>
- <xsl:otherwise>
- <xsl:apply-templates select="./parameter"/>
- </xsl:otherwise>
- </xsl:choose>
- <xsl:choose>
- <xsl:when test="following-sibling::paramdef">
- <xsl:text>, </xsl:text>
- </xsl:when>
- <xsl:otherwise>
- <xsl:text> )</xsl:text>
- </xsl:otherwise>
- </xsl:choose>
-</xsl:template>
-
-<xsl:template match="paramdef/type">
- <xsl:apply-templates/>
- <xsl:text> </xsl:text>
-</xsl:template>
-
-<!-- default values for function parameters -->
-<xsl:template match="paramdef/initializer">
- <xsl:text> = </xsl:text>
- <xsl:apply-templates/>
-</xsl:template>
-
-
-</xsl:stylesheet>
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 @@
-<?xml version='1.0'?>
-<xsl:stylesheet
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
-<!--
- Customization xsl stylesheet for docbook to chunked html transform
- @author Gaetano Giunta
- @copyright (c) 2007-2015 G. Giunta
- @license code licensed under the BSD License
-
- @todo make the xsl more dynamic: the path to import chunk.xsl could be f.e. rewritten/injected by the php user.
- This would be needed f.e. if the lib is installed as a dependency and is not the top-level composer project.
- Note: according to http://stackoverflow.com/questions/9861355/using-dynamic-href-in-xslt-import-include this is
- not easy to do - it would have to be done f.e. by the invoking php script...
--->
-
-
-<!-- import base stylesheet -->
-<xsl:import href="%docbook-chunk.xsl%"/>
-
-
-<!-- customization vars -->
-<xsl:param name="draft.mode">no</xsl:param>
-<xsl:param name="funcsynopsis.style">ansi</xsl:param>
-<xsl:param name="html.stylesheet">xmlrpc.css</xsl:param>
-<xsl:param name="id.warnings">0</xsl:param>
-
-
-<!-- elements added / modified -->
-
-<!-- space between function name and opening parenthesis -->
-<xsl:template match="funcdef" mode="ansi-nontabular">
- <code>
- <xsl:apply-templates select="." mode="class.attribute"/>
- <xsl:apply-templates mode="ansi-nontabular"/>
- <xsl:text> ( </xsl:text>
- </code>
-</xsl:template>
-
-<!-- space between return type and function name -->
-<xsl:template match="funcdef/type" mode="ansi-nontabular">
- <xsl:apply-templates mode="ansi-nontabular"/>
- <xsl:text> </xsl:text>
-</xsl:template>
-
-<!-- space between last param and closing parenthesis, remove tailing semicolon -->
-<xsl:template match="void" mode="ansi-nontabular">
- <code>void )</code>
-</xsl:template>
-
-<xsl:template match="varargs" mode="ansi-nontabular">
- <xsl:text>...</xsl:text>
- <code> )</code>
-</xsl:template>
-
-<xsl:template match="paramdef" mode="ansi-nontabular">
- <xsl:apply-templates mode="ansi-nontabular"/>
- <xsl:choose>
- <xsl:when test="following-sibling::*">
- <xsl:text>, </xsl:text>
- </xsl:when>
- <xsl:otherwise>
- <code> )</code>
- </xsl:otherwise>
- </xsl:choose>
-</xsl:template>
-
-<!-- param types get code formatted (leave a space after type, as it is supposed to be before param name) -->
-<xsl:template match="paramdef/type" mode="ansi-nontabular">
- <xsl:choose>
- <xsl:when test="$funcsynopsis.decoration != 0">
- <code>
- <xsl:apply-templates mode="ansi-nontabular"/>
- </code>
- </xsl:when>
- <xsl:otherwise>
- <code>
- <xsl:apply-templates mode="ansi-nontabular"/>
- </code>
- </xsl:otherwise>
- </xsl:choose>
- <xsl:text> </xsl:text>
-</xsl:template>
-
-<!-- default values for function parameters -->
-<xsl:template match="paramdef/initializer" mode="ansi-nontabular">
- <xsl:text> = </xsl:text>
- <xsl:apply-templates mode="ansi-nontabular"/>
-</xsl:template>
-
-
-</xsl:stylesheet>
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"