Merge pull request #2143 from jimklimov/issue-2142

Adapt to builds with Slackware 15

configure.ac

@@ -2556,11 +2556,13 @@ dnl to detect if we can build the wanted documentation format and yet
 dnl not fail if we have no tools to generate it (so add to SKIP list).
 
 	html-single*)
-		AC_MSG_CHECKING([if asciidoc version can build ${nut_doc_build_target_base} (minimum required ${ASCIIDOC_MIN_VERSION})])
+		AC_MSG_CHECKING([if asciidoc and a2x versions can build ${nut_doc_build_target_base} (minimum required asciidoc-${ASCIIDOC_MIN_VERSION} a2x-${A2X_MIN_VERSION})])
 		can_build_doc_html_single=no
 		AX_COMPARE_VERSION([${ASCIIDOC_VERSION}], [ge], [${ASCIIDOC_MIN_VERSION}], [
-			( cd "$DOCTESTDIR" && ${A2X} --attribute=xhtml11_format --format=xhtml --xsl-file="${abs_srcdir}"/docs/xhtml.xsl --destination-dir=. "${abs_srcdir}"/docs/asciidoc.txt && test -s asciidoc.html ) && can_build_doc_html_single=yes
-			rm -f "$DOCTESTDIR"/asciidoc*.htm*
+			AX_COMPARE_VERSION([${A2X_VERSION}], [ge], [${A2X_MIN_VERSION}], [
+				( cd "$DOCTESTDIR" && ${A2X} --attribute=xhtml11_format --format=xhtml --xsl-file="${abs_srcdir}"/docs/xhtml.xsl --destination-dir=. "${abs_srcdir}"/docs/asciidoc.txt && test -s asciidoc.html ) && can_build_doc_html_single=yes
+				rm -f "$DOCTESTDIR"/asciidoc*.htm*
+			], [])
 		], [])
 		if test "${can_build_doc_html_single}" = yes ; then
 			AC_MSG_RESULT(yes)
@@ -2577,11 +2579,13 @@ dnl not fail if we have no tools to generate it (so add to SKIP list).
 		;;
 
 	html-chunked*)
-		AC_MSG_CHECKING([if a2x version can build ${nut_doc_build_target_base} (minimum required ${ASCIIDOC_MIN_VERSION})])
+		AC_MSG_CHECKING([if asciidoc and a2x versions can build ${nut_doc_build_target_base} (minimum required asciidoc-${ASCIIDOC_MIN_VERSION} a2x-${A2X_MIN_VERSION})])
 		can_build_doc_html_chunked=no
-		AX_COMPARE_VERSION([${A2X_VERSION}], [ge], [${ASCIIDOC_MIN_VERSION}], [
-			( cd "$DOCTESTDIR" && ${A2X} --attribute=chunked_format --format=chunked --xsl-file="${abs_srcdir}"/docs/chunked.xsl --destination-dir=. "${abs_srcdir}"/docs/FAQ.txt && test -s FAQ.chunked/index.html ) && can_build_doc_html_chunked=yes
-			rm -rf "${DOCTESTDIR}"/FAQ*.chunked*
+		AX_COMPARE_VERSION([${ASCIIDOC_VERSION}], [ge], [${ASCIIDOC_MIN_VERSION}], [
+			AX_COMPARE_VERSION([${A2X_VERSION}], [ge], [${A2X_MIN_VERSION}], [
+				( cd "$DOCTESTDIR" && ${A2X} --attribute=chunked_format --format=chunked --xsl-file="${abs_srcdir}"/docs/chunked.xsl --destination-dir=. "${abs_srcdir}"/docs/FAQ.txt && test -s FAQ.chunked/index.html ) && can_build_doc_html_chunked=yes
+				rm -rf "${DOCTESTDIR}"/FAQ*.chunked*
+			], [])
 		], [])
 		if test "${can_build_doc_html_chunked}" = yes ; then
 			AC_MSG_RESULT(yes)
@@ -2785,8 +2789,16 @@ if test "x$WINDMC" != "xnone" -a "x$WINDRES" != "xnone" ; then
 fi
 
 AM_CONDITIONAL([HAVE_MINGW_RESGEN], [test "${nut_have_mingw_resgen}" = "yes"])
-dnl Also define a generic AM_CONDITIONAL for general Windows compilation
-AM_CONDITIONAL([HAVE_WINDOWS], [test "${nut_have_mingw_resgen}" = "yes"])
+
+dnl Also define a generic automake condition for general Windows compilation:
+dnl do we at least have the header file(s) we require for the platform
+dnl (more files may be optional e.g. for different generations of networking)
+dnl Could just use ..._COND_IF([HAVE_WINDOWS_H],... but it is not present in
+dnl some older versions of autotools. (Note autoconf expands in comments too).
+AS_IF([test "x$nut_cv_header_windows_h" = xyes],
+	[AM_CONDITIONAL([HAVE_WINDOWS], [test "${nut_have_mingw_resgen}" = "yes"])],
+	[AM_CONDITIONAL([HAVE_WINDOWS], [false])]
+	)
 
 dnl ----------------------------------------------------------------------
 

docs/Makefile.am

@@ -179,6 +179,7 @@ DOCBUILD_FILTER_GITHUB_LINKS = { \
         -e 's%\#\(\#[1-9][0-9]*\)%\1%g' \
 ; }
 
+# The $< is okay here, it is used in a suffix rule below
 DOCBUILD_CONVERT_GITHUB_LINKS = { \
     echo "  DOC-ASCIIDOC-GITHUB-LINKS    Parsing GitHub link patterns $< => $@"; \
     cat "$<" | $(DOCBUILD_FILTER_GITHUB_LINKS) > "$@.tmp" \
@@ -482,14 +483,14 @@ spellcheck-sortdict: $(abs_builddir)/$(NUT_SPELL_DICT).sorted
 $(abs_builddir)/$(NUT_SPELL_DICT).sorted: $(abs_srcdir)/$(NUT_SPELL_DICT)
 	@cp -pf $(abs_srcdir)/$(NUT_SPELL_DICT) $(abs_builddir)/$(NUT_SPELL_DICT).bak-pre-sorting
 	@LANG=$(ASPELL_ENV_LANG); LC_ALL=$(ASPELL_ENV_LANG); export LANG; export LC_ALL; ( \
-	    WORDLIST="`tail -n +2 < "$<" | sort | uniq`"; \
+	    WORDLIST="`tail -n +2 < "$?" | sort | uniq`"; \
 	    WORDCOUNT="`echo "$$WORDLIST" | wc -l`"; \
-	    head -1 < "$<" | while read P L C E ; do echo "$$P $$L $$WORDCOUNT $$E"; break; done ; \
+	    head -1 < "$?" | while read P L C E ; do echo "$$P $$L $$WORDCOUNT $$E"; break; done ; \
 	    echo "$$WORDLIST"; \
 	 ) > "$@"
 	@cp -f "$@" "$(abs_builddir)/$(NUT_SPELL_DICT)"
 	@if [ "$(abs_builddir)" != "$(abs_srcdir)" ] ; then \
-	    cp -f "$@" "$<" || true ; \
+	    cp -f "$@" "$?" || true ; \
 	    cp -f "$(abs_builddir)/$(NUT_SPELL_DICT).bak-pre-sorting" "$(abs_srcdir)/" || true ; \
 	 fi
 

docs/config-prereqs.txt

@@ -495,6 +495,154 @@ required:
     jre11-openjdk-headless
 ------
 
+Slackware Linux 15
+~~~~~~~~~~~~~~~~~~
+
+Another long-term presence in the Linux landscape, and sometimes the baseline
+for appliances, the Slackware project recently hit release 15 in 2002, averaging
+two years per major release.
+
+It can be installed e.g. in a VM, using ISO images from the project site; see:
+
+* http://www.slackware.com/ => http://www.slackware.com/getslack/ =>
+  https://mirrors.slackware.com/slackware/slackware-iso/slackware64-15.0-iso/
+* https://slackware.nl/slackware/slackware64-current-iso/
+
+You would have to first log in as `root` and run `cgdisk` to define partitioning
+for your virtual HDD, such as the common `/boot`, `swap` and `/` Linux layout,
+and run `setup` to install "everything".
+
+Note that "out of the box" Slackware does not currently on networked package
+repositories and calculated dependency trees, so one has to know exactly what
+they want installed.
+
+Third-party projects for package managers are also available, e.g.
+link:https://slackpkg.org/documentation.html[`slackpkg`] => see also
+https://docs.slackware.com/slackware:slackpkg and
+https://slackpkg.org/stable/ :
+----
+:; wget https://slackpkg.org/stable/slackpkg-15.0.10-noarch-1.txz && \
+   installpkg slackpkg-15.0.10-noarch-1.txz
+----
+
+Uncomment a mirror from `/etc/slackpkg/mirrors` according to your location
+and other preferences (or use the top-listed default), and begin with:
+----
+:; slackpkg update
+----
+
+Note that packages may be only installed or re-installed/upgraded as separate
+explicit operations, so the procedure to bring your system into needed shape
+is a bit cumbersome (and each command may by default be interactive with a
+choice menu), e.g.:
+----
+:; for P in \
+    bash mc vim sudo \
+   ; do slackpkg info "$P" || slackpkg install $P || break ; done
+----
+
+For procedures below, this is automated via `root` profile to become a
+`slackpkg-install` command:
+----
+:; grep "slackpkg-install" ~/.profile || {
+    echo 'slackpkg-install() { for P in "$@" ; do echo "=== $P:"; slackpkg info "$P" || slackpkg install "$P" || break ; done; }' >> ~/.profile
+   }
+:; . ~/.profile
+----
+
+If something has a hiccup, it suggests to look for the right name, e.g.:
+----
+:; slackpkg search python
+----
+
+For NUT dependencies and build tools:
+----
+:; slackpkg update
+
+# Baseline toolkits:
+# Note there is no cppcheck, cppunit, valgrind...
+# Note clang compiler tools are part of llvm package
+:; slackpkg-install \
+    ccache time \
+    coreutils diffutils \
+    git python3 perl curl \
+    make autoconf automake libtool binutils \
+    pkg-config \
+    gcc llvm
+
+# For spell-checking, highly recommended if you would propose pull requests:
+:; slackpkg-install aspell{,-en}
+
+# Note there is no direct "asciidoc" nor "a2x", just the competing project
+# "rubygem-asciidoctor" that NUT currently has no recipes for, so you can
+# not compile man/html/pdf docs here, per the default repository. See below
+# for tools from alternative repositories, which seem to work well. Manpage
+# compilation would require docbook-xml resources; older versions are in
+# this package https://slackbuilds.org/repository/15.0/system/docbook-xml/
+# and recent ones are in not-installed part of main repository:
+:; slackpkg-install linuxdoc-tools
+
+# More on Python (for NUT-Monitor UI):
+:; slackpkg-install \
+    python-pip qt5 gettext-tools gettext
+
+# For CGI graph generation - massive packages (X11):
+:; slackpkg-install \
+    gd
+
+# General dependencies:
+:; slackpkg-install \
+    openssl openssl-solibs mozilla-nss \
+    libusb \
+    net-snmp \
+    neon
+
+# Shells:
+:; slackpkg-install \
+    bash dash ksh93
+----
+
+Some more packages are available on the side, including Java (useful
+e.g. to make this environment into a fully fledged Jenkins worker).
+Other common NUT dependencies absent from primary Slackware repositories
+can be found and downloaded (seek `*.txz` package files, although a few
+are named `*.tgz`) from here, and passed to `installpkg`:
+
+* http://www.slackware.com/~alien/slackbuilds/openjdk11/
+* http://www.slackware.com/~alien/slackbuilds/asciidoc/
+* http://www.slackware.com/~alien/slackbuilds/cppunit/
+* http://www.slackware.com/~alien/slackbuilds/lua/ (5.1 currently) and
+  http://www.slackware.com/~alien/slackbuilds/lua53/ -- note that LUA is not
+  needed for the current NUT code base, but may become needed after import
+  of features from forks
+
+...and even the environment for Windows cross-builds, ancient compilers
+and modern toolkits to cover all bases:
+
+* http://www.slackware.com/~alien/slackbuilds/MinGW-w64/
+* http://www.slackware.com/~alien/slackbuilds/docker/
+* http://www.slackware.com/~alien/slackbuilds/gcc34/
+* http://www.slackware.com/~alien/slackbuilds/gcc5/
+
+FWIW, another "more official" but older Java package seems to be at:
+
+* http://www.slackware.com/~alien/slackbuilds/openjdk/
+* https://slackbuilds.org/repository/15.0/development/jdk/
+
+An example routine to install the latest instance of a package could be
+like this:
+----
+:; wget -m -l1 http://www.slackware.com/~alien/slackbuilds/asciidoc/pkg/ && \
+    find . -name '*.t?z'
+
+:; installpkg ./www.slackware.com/~alien/slackbuilds/asciidoc/pkg/asciidoc-8.1.0-noarch-2.tgz
+----
+
+Upon community members' recommendations, Sotirov's SlackPack is also considered
+a reputable repository: https://sotirov-bg.net/slackpack/ and should cover most
+if not all of the dependencies required for NUT building (including PowerMan,
+IPMI etc.)
+
 FreeBSD 12.2
 ~~~~~~~~~~~~
 

docs/man/al175.txt

@@ -6,10 +6,14 @@ NAME
 
 al175 - Driver for Eltek UPS models with AL175 alarm module
 
-NOTE
-----
+SYNOPSIS
+--------
+
+*al175* -h
+
+*al175* -a 'UPS_NAME' ['OPTIONS']
 
-This man page only documents the hardware-specific features of the
+NOTE: This man page only documents the hardware-specific features of the
 *al175* driver. For information about the core driver, see
 linkman:nutupsdrv[8].
 

docs/man/apc_modbus.txt

@@ -6,6 +6,13 @@ NAME
 
 apc_modbus - Driver for APC Smart-UPS Modbus protocol
 
+SYNOPSIS
+--------
+
+*apc_modbus* -h
+
+*apc_modbus* -a 'UPS_NAME' ['OPTIONS']
+
 SUPPORTED HARDWARE
 ------------------
 

docs/man/apcupsd-ups.txt

@@ -6,10 +6,14 @@ NAME
 
 apcupsd-ups - Driver for apcupsd client access
 
-NOTE
-----
+SYNOPSIS
+--------
+
+*apcupsd-ups* -h
+
+*apcupsd-ups* -a 'UPS_NAME' ['OPTIONS']
 
-This man page only documents the specific features of the
+NOTE: This man page only documents the specific features of the
 *apcupsd-ups* driver.  For information about the core driver, see
 linkman:nutupsdrv[8].
 

docs/man/asem.txt

@@ -6,10 +6,14 @@ NAME
 
 asem - driver for UPS in ASEM PB1300
 
-NOTE
-----
+SYNOPSIS
+--------
+
+*asem* -h
+
+*asem* -a 'UPS_NAME' ['OPTIONS']
 
-This man page only documents the hardware-specific features of the
+NOTE: This man page only documents the hardware-specific features of the
 *asem* driver.  For information about the core driver, see
 linkman:nutupsdrv[8].
 

docs/man/bcmxcp.txt

@@ -6,10 +6,14 @@ NAME
 
 bcmxcp - Driver for UPSes supporting the serial BCM/XCP protocol
 
-NOTE
-----
+SYNOPSIS
+--------
+
+*bcmxcp* -h
+
+*bcmxcp* -a 'UPS_NAME' ['OPTIONS']
 
-This man page only documents the hardware-specific features of the
+NOTE: This man page only documents the hardware-specific features of the
 bcmxcp driver.  For information about the core driver, see
 linkman:nutupsdrv[8].
 

docs/man/bcmxcp_usb.txt

@@ -7,14 +7,19 @@ NAME
 bcmxcp_usb - Experimental driver for UPSes supporting the BCM/XCP protocol
 over USB
 
-NOTE
-----
+SYNOPSIS
+--------
+
+*bcmxcp_usb* -h
 
-This man page only documents the hardware-specific features of the
+*bcmxcp_usb* -a 'UPS_NAME' ['OPTIONS']
+
+NOTE: This man page only documents the hardware-specific features of the
 bcmxcp_usb driver.  For information about the core driver, see
 linkman:nutupsdrv[8].
-This driver is a variant of the serial driver bcmxcp and uses the same
-core code.
+
+NOTE: This driver is a variant of the serial driver linkman:bcmxcp[8] and
+uses the same core code.
 
 SUPPORTED HARDWARE
 ------------------

docs/man/belkin.txt

@@ -6,10 +6,14 @@ NAME
 
 belkin - Driver for Belkin serial UPS equipment
 
-NOTE
-----
+SYNOPSIS
+--------
+
+*belkin* -h
+
+*belkin* -a 'UPS_NAME' ['OPTIONS']
 
-This man page only documents the hardware-specific features of the
+NOTE: This man page only documents the hardware-specific features of the
 belkin driver.  For information about the core driver, see
 linkman:nutupsdrv[8].
 

docs/man/belkinunv.txt

@@ -6,15 +6,19 @@ NAME
 
 belkinunv - Driver for Belkin "Universal UPS" and compatible
 
-NOTE
-----
+SYNOPSIS
+--------
+
+*belkinunv* -h
+
+*belkinunv* -a 'UPS_NAME' ['OPTIONS']
 
-This man page only documents the hardware-specific features of the
+NOTE: This man page only documents the hardware-specific features of the
 belkin driver.  For information about the core driver, see
 linkman:nutupsdrv[8].
 
-This driver only supports serial connections. If your UPS has a USB port,
-please consult the Hardware Compatibility List (HCL) to see which of
+NOTE: This driver only supports serial connections. If your UPS has a USB
+port, please consult the Hardware Compatibility List (HCL) to see which of
 the USB drivers you should use.
 
 SUPPORTED HARDWARE