document generation improvements (GPSBabel#937)

* build docs on macos CI.

* add fop for macos ci

* block out of source doc builds, change WEB default.

* add gnu-sed for macos fixdoc

* set default logger for fop

with homebrew fop 2.7 the default logger is something else besides
SimpleLog.
The LOGLEVEL statement is specific to SimpleLog.

.foprc

@@ -1 +1,2 @@
+LOGCHOICE=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
 LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN

.github/workflows/macos.yml

@@ -60,8 +60,11 @@ jobs:
       run: |
         brew update
         brew install ninja
+        brew install docbook docbook-xsl fop gnu-sed
 
     - name: Script
+      env:
+        XML_CATALOG_FILES: /usr/local/etc/xml/catalog
       run: |
         source ${HOME}/Cache/qt-${{ matrix.QT_VERSION }}.env
         sudo xcode-select --switch /Applications/Xcode_${{ matrix.XCODE_VERSION }}.app

CMakeLists.txt

@@ -489,22 +489,23 @@ if(UNIX AND NOT APPLE)
                     USES_TERMINAL)
 endif()
 
-if(CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR)
-  set(WEB "../babelweb" CACHE PATH "Path where the documentation will be stored for www.gpsbabel.org.")
+get_property(_isMultiConfig GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
+if((CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR) AND NOT _isMultiConfig)
+  set(WEB "gpsbabel.org" CACHE PATH "Path where the documentation will be stored for www.gpsbabel.org.")
   add_custom_target(gpsbabel.org
                     ${CMAKE_SOURCE_DIR}/tools/make_gpsbabel_org.sh ${WEB} ${DOCVERSION}
                     DEPENDS gpsbabel gpsbabel.pdf
                     VERBATIM)
-endif()
 
-if(CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR)
   add_custom_target(gpsbabel.html
                     ${CMAKE_SOURCE_DIR}/tools/make_gpsbabel_html.sh
-                    DEPENDS gpsbabel)
-endif()
+                    DEPENDS gpsbabel
+                    VERBATIM)
 
-if(CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR)
   add_custom_target(gpsbabel.pdf
                     ${CMAKE_SOURCE_DIR}/tools/make_gpsbabel_pdf.sh
-                    DEPENDS gpsbabel)
+                    DEPENDS gpsbabel
+                    VERBATIM)
+else()
+  message(WARNING "Document generation is only supported for in-source builds with single configuration generators.")
 endif()

tools/build_and_test_cmake.sh

@@ -15,7 +15,7 @@ git --no-pager log -n 1
 # build and test keeping output within the pwd.
 export GBTEMP=$(pwd)/gbtemp
 mkdir -p "$GBTEMP"
-cmake . -G Ninja -DCMAKE_BUILD_TYPE=Release -DWEB="$(pwd)/gpsbabel_docdir"
+cmake . -G Ninja -DCMAKE_BUILD_TYPE=Release
 # As of 2018-10, all the virtualized travis build images are two cores per:
 # https://docs.travis-ci.com/user/reference/overview/
 # We'll be slightly abusive on CPU knowing that I/O is virtualized.

tools/ci_script_osx.sh

@@ -46,6 +46,9 @@ Xcode | "Ninja Multi-Config")
   cmake --build .
   ctest
   cmake --build . --target package_app
+  cmake --build . --target gpsbabel.html
+  cmake --build . --target gpsbabel.pdf
+  cmake --build . --target gpsbabel.org
   ;;
 esac
 

tools/make_gpsbabel_org.sh

@@ -6,8 +6,7 @@ docversion=$2
 
 mkdir -p "${web}/htmldoc-${docversion}"
 perl xmldoc/makedoc
-xmlwf xmldoc/readme.xml #check for well-formedness
-xmllint --noout --valid xmldoc/readme.xml #validate
+xmllint --noout --valid xmldoc/readme.xml #valid and well-formed
 xsltproc \
   --stringparam base.dir "${web}/htmldoc-${docversion}/" \
   --stringparam root.filename "index" \

tools/make_gpsbabel_pdf.sh

@@ -2,7 +2,6 @@
 set -ex
 
 perl xmldoc/makedoc
-xmlwf xmldoc/readme.xml #check for well-formedness
-xmllint --noout --valid xmldoc/readme.xml #validate
+xmllint --noout --valid xmldoc/readme.xml #valid and well-formed
 xsltproc -o gpsbabel.fo xmldoc/babelpdf.xsl xmldoc/readme.xml
 HOME=. fop -q -fo gpsbabel.fo -pdf gpsbabel.pdf