Try to fix GitHub release build Workflow failing to build source docu…

…mentation.

- Update `tools/doxygen/doxygen.sh` script (and a few otther tool scripts) to check out as executable.
- Include PlantUML tool in repository.

tools/doxygen/doxygen.bat

@@ -2,7 +2,8 @@
 
 if "%~1" == "" goto :PARAMETER_ERROR
 
-rem set PLANTUML_JAR_PATH=C:\Program Files\PlantUML
+pushd "%~dp0"
+set PLANTUML_JAR_PATH=%CD%/plantuml
 
 call "../windows/get-source-version.bat" "../../source/base/version.h"
 set POV_VER=%POV_SOURCE_VERSION%
@@ -29,6 +30,7 @@ goto :EOF
 
 :DOXYGEN_FAIL
 popd
+popd
 echo *** FAILED TO GENERATE SOURCE DOCUMENTATION ***
 pause
 goto :EOF

tools/doxygen/doxygen.sh

@@ -1,15 +1,37 @@
 #!/bin/bash
 
-# export PLANTUML_JAR_PATH='/usr/bin'
+# Remember the directory we're currently working in.
+olddir=`pwd`
 
+# Make sure we're (initially) working in the directory this script resides in.
+cd `dirname $0`
+
+export PLANTUML_JAR_PATH=`pwd`/plantuml
+
+# The next steps expect us to be working in the source tree root directory.
 cd ../..
+
 eval `tools/unix/get-source-version.sh source/base/version.h`
 export POV_VER="$POV_RAY_FULL_VERSION"
-doxygen tools/doxygen/source-doc.cfg
-cd tools/doxygen
+if ! doxygen tools/doxygen/source-doc.cfg ; then
+  cd "$olddir"
+  exit 1
+fi
+
+# The step to generate the PDF version expects us to be working in the
+# output directory of the LaTeX version
+cd tools/doxygen/source-doc/latex
 
-cd source-doc/latex
-make pdf
+if ! make pdf ; then
+  cd "$olddir"
+  exit 1
+fi
+
+# We choose to do the final steps working in the directory this script resides in.
 cd ../..
-mkdir pdf
-cp "source-doc/latex/refman.pdf" "source-doc/pdf/POV-Ray Developer Manual.pdf"
+
+mkdir source-doc/pdf
+cp "source-doc/latex/refman.pdf" "source-doc/pdf/povray-v$POV_RAY_FULL_VERSION-sourcedoc.pdf"
+
+# Let's go back to whatever directory we were initially working in.
+cd "$olddir"

tools/doxygen/plantuml/readme-pov.md

@@ -0,0 +1,24 @@
+PlantUML
+========
+
+We're using PlantUML as a minor part of our process to generate a Developer's
+Manual. The PlantUML software is included in the POV-Ray source tree for
+technical reasons only, to facilitate automated generation of said manual:
+We need the Java archive (jar file) variant, while Linux distributions (e.g.
+Ubuntu) will typically provide only a package containing some GUI variant;
+and while an official site for downloading the jar file does exist, it is
+hosted by SourceForge, and designed specifically to make automated download a
+major pain.
+
+To find out what version of PlantUML we're currently including, run:
+
+~~~
+java -jar plantuml.jar -version
+~~~
+
+To view the licensing terms and conditions of the PlantUML version we're
+currently including, run:
+
+~~~
+java -jar plantuml.jar -license
+~~~

tools/doxygen/readme.md

@@ -1,16 +1,28 @@
-To build the POV-Ray source documentation, you need the following pieces of software:
+Building the POV-Ray Developer's Manual
+=======================================
 
-  - **Doxygen**: Version 1.8.12 or higher is recommended; earlier versions _will_ generate flawed output.
+We're maintaining the bulk of the documentation of POV-Ray's inner workings in the form of
+comments embedded in the source files themselves, adhering to certain formalisms that allow us
+to use Doxygen (along with a few auxiliary tools) to compile that source documentation into a
+Developer's Manual.
+
+To generate the POV-Ray Developer's Manual, you need the following pieces of software:
+
+  - **Doxygen**: Version 1.8.17 has successfully been tested; later versions may work just as fine.
   - **Graphviz Toolkit**: Version 2.26.3 or higher is recommended; version 2.38 has successfully been tested.
   - **Java**: Version 1.7.0 has successfully been tested; other versions may work just as fine.
-  - **PlantUML**: Version 8018 has successfully been tested; other versions may work just as fine.
   - **LaTeX and GhostScript**: These are only required for PDF generation. On Windows we recommend MiKTeX 2.9 or higher,
     which includes GhostScript and has successfully been tested; other packages may work just as fine.
 
-All of the above are presumed to be found in the command search path, with the exception of PlantUML which is presumed
-to be named `plantuml.jar` and located in the directory specified by the environment variable PLANTUML_JAR_PATH.
+All of the above are presumed to be found in the command search path.
+
+The following pieces of software are also required, but included in POV-Ray's source tree for convenience,
+and expected to reside there as provided:
+
+  - **PlantUML**: Currently (2021-06-29), we're providing version 1.2021.8 (GPL 3 edition); other
+    versions may work just as fine. (Note that we need the JAR file version, not the executable
+    provided by some Linux distributions.)
 
-To build the source documentation on Windows, run the `source-doc.bat` batch file in this directory.
+To build the source documentation on Windows, run the `tools/doxygen/source-doc.bat` batch file.
 
-For Unix users we currently provide only a minimalistic _untested_ shell script, `doxygen.sh`, to build the
-source documentation.
+To build the source documentation on Unix, run the `tools/doxygen/doxygen.sh` shell script.

tools/doxygen/source-doc.bat

@@ -1,2 +1,8 @@
 @echo off
-call doxygen.bat "source-doc" "source-doc\pdf\POV-Ray Developer Manual.pdf"
+
+pushd "%~dp0"
+
+call "../windows/get-source-version.bat" "../../source/base/version.h"
+call doxygen.bat "source-doc" "source-doc\pdf\povray-v%POV_RAY_FULL_VERSION%-sourcedoc.pdf"
+
+popd