Merge pull request #2799 from jimklimov/fix-docs-markup

More fixes to docs markup, recipes, scripting

Makefile.am

@@ -199,7 +199,7 @@ spellcheck spellcheck-interactive:
 # texts, man pages and HTML rendering of man pages, as enabled by tools.
 doc spellcheck-sortdict spellcheck-report-dict-usage \
 all-docs check-docs \
-man all-man man-man check-man html-man all-html:
+man all-man man-man check-man check-man-man html-man all-html:
 	+cd $(abs_top_builddir)/docs && $(MAKE) $(AM_MAKEFLAGS) -s $(abs_top_builddir)/docs/.prep-src-docs
 	+cd $(abs_top_builddir)/docs/man && $(MAKE) $(AM_MAKEFLAGS) -s $(abs_top_builddir)/docs/man/.prep-src-docs
 	+cd $(abs_top_builddir)/docs && $(MAKE) $(AM_MAKEFLAGS) $@

ci_build.sh

@@ -22,6 +22,9 @@ SCRIPT_ARGS=("$@")
 # (and then easily `make` to iterate fixes), like this:
 #   CI_REQUIRE_GOOD_GITIGNORE="false" CI_FAILFAST=true DO_CLEAN_CHECK=no BUILD_TYPE=fightwarn ./ci_build.sh
 #
+# For in-place build configurations you can pass `INPLACE_RUNTIME=true`
+# (for common BUILD_TYPE's) or call `./ci_build.sh inplace`
+#
 # For out-of-tree builds you can specify a CI_BUILDDIR (absolute or relative
 # to SCRIPTDIR - not current path), or just call .../ci_build.sh while being
 # in a different directory and then it would be used with a warning. This may
@@ -1328,44 +1331,65 @@ optional_dist_clean_check() {
     return 0
 }
 
-if [ "$1" = inplace ] && [ -z "$BUILD_TYPE" ] ; then
-    shift
-    BUILD_TYPE="inplace"
-fi
+# Link a few BUILD_TYPEs to command-line arguments
+if [ -z "$BUILD_TYPE" ] ; then
+    case "$1" in
+        inplace)
+            # Note: causes a developer-style build (not CI)
+            shift
+            BUILD_TYPE="inplace"
+            ;;
 
-if [ "$1" = spellcheck -o "$1" = spellcheck-interactive ] && [ -z "$BUILD_TYPE" ] ; then
-    # Note: this is a little hack to reduce typing
-    # and scrolling in (docs) developer iterations.
-    case "$CI_OS_NAME" in
-        windows-msys2)
-            # https://github.com/msys2/MSYS2-packages/issues/2088
-            echo "=========================================================================="
-            echo "WARNING: some MSYS2 builds of aspell are broken with 'tex' support"
-            echo "Are you sure you run this in a functional build environment? Ctrl+C if not"
-            echo "=========================================================================="
-            sleep 5
+        docs|docs=*|doc|doc=*)
+            # Note: causes a developer-style build (not CI)
+            # Arg will be passed to configure script as `--with-$1`
+            BUILD_TYPE="$1"
+            shift
             ;;
-        *)  if ! (command -v aspell) 2>/dev/null >/dev/null ; then
-                echo "=========================================================================="
-                echo "WARNING: Seems you do not have 'aspell' in PATH (but maybe NUT configure"
-                echo "script would find the spellchecking toolkit elsewhere)"
-                echo "Are you sure you run this in a functional build environment? Ctrl+C if not"
-                echo "=========================================================================="
-                sleep 5
+
+        win64|cross-windows-mingw64) BUILD_TYPE="cross-windows-mingw64" ; shift ;;
+
+        win32|cross-windows-mingw32) BUILD_TYPE="cross-windows-mingw32" ; shift ;;
+
+        win|cross-windows-mingw) BUILD_TYPE="cross-windows-mingw" ; shift ;;
+
+        spellcheck|spellcheck-interactive)
+            # Note: this is a little hack to reduce typing
+            # and scrolling in (docs) developer iterations.
+            case "$CI_OS_NAME" in
+                windows-msys2)
+                    # https://github.com/msys2/MSYS2-packages/issues/2088
+                    echo "=========================================================================="
+                    echo "WARNING: some MSYS2 builds of aspell are broken with 'tex' support"
+                    echo "Are you sure you run this in a functional build environment? Ctrl+C if not"
+                    echo "=========================================================================="
+                    sleep 5
+                    ;;
+                *)  if ! (command -v aspell) 2>/dev/null >/dev/null ; then
+                        echo "=========================================================================="
+                        echo "WARNING: Seems you do not have 'aspell' in PATH (but maybe NUT configure"
+                        echo "script would find the spellchecking toolkit elsewhere)"
+                        echo "Are you sure you run this in a functional build environment? Ctrl+C if not"
+                        echo "=========================================================================="
+                        sleep 5
+                    fi
+                    ;;
+            esac >&2
+            if [ -s Makefile ] && [ -s docs/Makefile ]; then
+                echo "Processing quick and quiet spellcheck with already existing recipe files, will only report errors if any ..."
+                build_to_only_catch_errors_target $1 ; exit
+            else
+                # TODO: Actually do it (default-spellcheck-interactive)?
+                if [ "$1" = spellcheck-interactive ] ; then
+                    echo "Only CI-building 'spellcheck', please do the interactive part manually if needed" >&2
+                fi
+                BUILD_TYPE="default-spellcheck"
+                shift
             fi
             ;;
-    esac >&2
-    if [ -s Makefile ] && [ -s docs/Makefile ]; then
-        echo "Processing quick and quiet spellcheck with already existing recipe files, will only report errors if any ..."
-        build_to_only_catch_errors_target $1 ; exit
-    else
-        # TODO: Actually do it (default-spellcheck-interactive)?
-        if [ "$1" = spellcheck-interactive ] ; then
-            echo "Only CI-building 'spellcheck', please do the interactive part manually if needed" >&2
-        fi
-        BUILD_TYPE="default-spellcheck"
-        shift
-    fi
+
+        *) echo "WARNING: Command-line argument '$1' wsa not recognized as a BUILD_TYPE alias" >&2 ;;
+    esac
 fi
 
 echo "Processing BUILD_TYPE='${BUILD_TYPE}' ..."
@@ -2282,8 +2306,13 @@ default|default-alldrv|default-alldrv:no-distcheck|default-all-errors|default-sp
 bindings)
     pushd "./bindings/${BINDING}" && ./ci_build.sh
     ;;
-""|inplace)
-    echo "WARNING: No BUILD_TYPE was specified, doing a minimal default ritual without any *required* build products and with developer-oriented options" >&2
+""|inplace|doc*)
+    if [ x"${BUILD_TYPE}" = x ] ; then
+        _msg="No BUILD_TYPE"
+    else
+        _msg="BUILD_TYPE='${BUILD_TYPE}'"
+    fi
+    echo "WARNING: ${_msg} was specified, doing a minimal default ritual without any *required* build products and with developer-oriented options" >&2
     if [ -n "${BUILD_WARNOPT}${BUILD_WARNFATAL}" ]; then
         echo "WARNING: BUILD_WARNOPT and BUILD_WARNFATAL settings are ignored in this mode (warnings are always enabled and fatal for these developer-oriented builds)" >&2
         sleep 5
@@ -2332,11 +2361,16 @@ bindings)
         --enable-warnings --enable-Werror \
         --enable-keep_nut_report_feature \
         --with-all=auto --with-cgi=auto --with-serial=auto \
-        --with-dev=auto --with-doc=skip \
+        --with-dev=auto \
         --with-nut_monitor=auto --with-pynut=auto \
         --disable-force-nut-version-header \
         --enable-check-NIT --enable-maintainer-mode)
 
+    case x"${BUILD_TYPE}" in
+        xdoc*) CONFIG_OPTS+=("--with-${BUILD_TYPE}") ;;
+        *) CONFIG_OPTS+=("--with-doc=skip") ;;
+    esac
+
     detect_platform_PKG_CONFIG_PATH_and_FLAGS
     if [ -n "$PKG_CONFIG_PATH" ] ; then
         CONFIG_OPTS+=("PKG_CONFIG_PATH=${PKG_CONFIG_PATH}")

configure.ac

@@ -3334,7 +3334,11 @@ dnl not fail if we have no tools to generate it (so add to SKIP list).
 		else
 			if test "${can_build_doc_man}" = yes ; then
 				AC_MSG_RESULT(yes)
-				DOC_BUILD_LIST="${DOC_BUILD_LIST} ${nut_doc_build_target_base}"
+				AS_IF([test x"${nut_doc_build_target_base}" = xman],
+					dnl Use "man-man" target, otherwise Makefile
+					dnl is satisfied that directory "man" exists:
+					[DOC_BUILD_LIST="${DOC_BUILD_LIST} man-man"],
+					[DOC_BUILD_LIST="${DOC_BUILD_LIST} ${nut_doc_build_target_base}"])
 			else
 				AC_MSG_RESULT(no)
 				if test "${nut_doc_build_target_flag}" = "yes" ; then
@@ -3399,6 +3403,7 @@ NUT_REPORT_FEATURE([build specific documentation format(s)], [${nut_with_doc}],
 DOC_CHECK_LIST=""
 if test "${nut_with_doc}" = yes ; then
 	for V in $DOC_BUILD_LIST ; do
+		if test x"$V" = xman-man ; then V=man ; fi
 		DOC_CHECK_LIST="$DOC_CHECK_LIST check-$V"
 	done
 fi

docs/Makefile.am

@@ -340,7 +340,7 @@ check-html-chunked: $(ASCIIDOC_HTML_CHUNKED)
 # Note: default `make all` in the man directory caters to drivers etc.
 # chosen during configure script execution. The "all-man" and "all-html"
 # rules build everything documented.
-check-man all-man man-man all-html html-man:
+check-man check-man-man all-man man-man all-html html-man:
 	+cd $(abs_top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile $@
 
 man:
@@ -466,6 +466,11 @@ A2X_COMMON_OPTS = $(ASCIIDOC_VERBOSE) \
     --attribute=builddir="$(abs_builddir)/" \
     --attribute=top_srcdir="$(abs_top_srcdir)/" \
     --attribute=top_builddir="$(abs_top_builddir)/" \
+    --attribute=MAN_SECTION_API_BASE='@MAN_SECTION_API_BASE@' \
+    --attribute=MAN_SECTION_CFG_BASE='@MAN_SECTION_CFG_BASE@' \
+    --attribute=MAN_SECTION_CMD_SYS_BASE='@MAN_SECTION_CMD_SYS_BASE@' \
+    --attribute=MAN_SECTION_CMD_USR_BASE='@MAN_SECTION_CMD_USR_BASE@' \
+    --attribute=NUT_WEBSITE_BASE='@NUT_WEBSITE_BASE@' \
     -a toc -a numbered --destination-dir=$${A2X_OUTDIR}
 # NOTE: a2x newer than 8.6.8 says "--destination-dir" is only valid for HTML.
 # As of version 8.6.9 it lies, and the argument is required for our distcheck
@@ -783,7 +788,7 @@ DISTCLEANFILES = $(NUT_SPELL_DICT).bak-pre-sorting .$(NUT_SPELL_DICT).sorted $(N
 # any future re-runs). We also must update all relevant *-spellchecked
 # touch-files after "make spellcheck-sortdict" which updates "nut.dict"
 # file which is a prerequisite for docs checks.
-spellcheck-interactive: 
+spellcheck-interactive:
 	@cp -pf $(abs_srcdir)/$(NUT_SPELL_DICT) $(abs_builddir)/$(NUT_SPELL_DICT).bak-pre-sorting
 	+@FAILED="" ; for docsrc in $(SPELLCHECK_SRC); do \
 		if test "$(SPELLCHECK_ENV_DEBUG)" != no ; then \
@@ -888,9 +893,11 @@ $(abs_top_builddir)/docs/.prep-src-docs: $(PREP_SRC)
 	                fi ;; \
 	        esac ; \
 	        if $$MAN_SECTIONS_DEFAULT ; then \
-	            cat ; \
+	            sed \
+	                -e 's,\(home page:\) https://www.networkupstools.org/*$$,\1 @NUT_WEBSITE_BASE@/,' ; \
 	        else \
 	            sed \
+	                -e 's,\(home page:\) https://www.networkupstools.org/*$$,\1 @NUT_WEBSITE_BASE@/,' \
 	                -e 's,\(linkman:[^ []*\[\)3\],\1$(MAN_SECTION_API)],g' \
 	                -e 's,\(linkman:[^ []*\[\)5\],\1$(MAN_SECTION_CFG)],g' \
 	                -e 's,\(linkman:[^ []*\[\)8\],\1$(MAN_SECTION_CMD_SYS)],g' \
@@ -942,9 +949,11 @@ $(abs_top_builddir)/docs/.prep-src-docs: $(PREP_SRC)
 	            grep -w linkman "$${linkroot}/$${F}" > /dev/null || IS_TEXT=false ; \
 	        fi ; \
 	        if $$MAN_SECTIONS_DEFAULT || ! $$IS_TEXT ; then \
-	            cat ; \
+	            sed \
+	                -e 's,\(home page:\) https://www.networkupstools.org/*$$,\1 @NUT_WEBSITE_BASE@/,' ; \
 	        else \
 	            sed \
+	                -e 's,\(home page:\) https://www.networkupstools.org/*$$,\1 @NUT_WEBSITE_BASE@/,' \
 	                -e 's,\(linkman:[^ []*\[\)3\],\1$(MAN_SECTION_API)],g' \
 	                -e 's,\(linkman:[^ []*\[\)5\],\1$(MAN_SECTION_CFG)],g' \
 	                -e 's,\(linkman:[^ []*\[\)8\],\1$(MAN_SECTION_CMD_SYS)],g' \

docs/man/Makefile.am

@@ -20,9 +20,24 @@
 #EGREP = egrep
 EGREP = grep -E
 
-all:
+ALL_TGT =
+if WITH_MANS
+ALL_TGT += all-man
+endif WITH_MANS
+if WITH_HTML_SINGLE
+ALL_TGT += all-html
+else !WITH_HTML_SINGLE
+if WITH_HTML_CHUNKED
+ALL_TGT += all-html
+endif WITH_HTML_CHUNKED
+endif !WITH_HTML_SINGLE
 
-all-am-local all-local: $(abs_top_builddir)/docs/man/.prep-src-docs
+all: $(abs_top_builddir)/docs/man/.prep-src-docs
+	+@case "$(ALL_TGT)" in \
+	  *all-*) \
+		echo "  DOC-FOLLOW-UP	Basic 'make $@' in `pwd` is done, following up with 'make $(ALL_TGT)' to ensure complex document types (if enabled)" ; \
+		$(MAKE) $(AM_MAKEFLAGS) $(ALL_TGT) ; exit ;; \
+	  esac ; exit 0
 
 # Base configuration and client manpages, always installed
 SRC_CONF_PAGES = \
@@ -1003,7 +1018,7 @@ check-local: check-man-txt check-man-pages
 	@echo "Man-page generation was not done, so pregenerated pages were sanity-checked (if any)" >&2
 endif
 
-check-man: check-man-txt check-man-pages check-html-man
+check-man check-man-man: check-man-txt check-man-pages check-html-man
 
 # the "for" loops might better use $^ but it might be not portable
 check-man-html: check-html-man
@@ -1130,27 +1145,32 @@ DOCBUILD_END = { \
 	 echo "  DOC-MAN-HTML Generating $@"; \
 	 $(DOCBUILD_BEGIN) ; RES=0; \
 	 $(ASCIIDOC) --backend=xhtml11 $${A2X_VERBOSE} \
-		--attribute localdate="`TZ=UTC date +%Y-%m-%d`" \
-		--attribute localtime="`TZ=UTC date +%H:%M:%S`" \
-		--attribute nutversion="@PACKAGE_VERSION@" \
-		--attribute srcdir="$(abs_srcdir)/" \
-		--attribute builddir="$(abs_builddir)/" \
-		--attribute top_srcdir="$(abs_top_srcdir)/" \
-		--attribute top_builddir="$(abs_top_builddir)/" \
+		--attribute=localdate="`TZ=UTC date +%Y-%m-%d`" \
+		--attribute=localtime="`TZ=UTC date +%H:%M:%S`" \
+		--attribute=nutversion="@PACKAGE_VERSION@" \
+		--attribute=srcdir="$(abs_srcdir)/" \
+		--attribute=builddir="$(abs_builddir)/" \
+		--attribute=top_srcdir="$(abs_top_srcdir)/" \
+		--attribute=top_builddir="$(abs_top_builddir)/" \
+		--attribute=MAN_SECTION_API_BASE='@MAN_SECTION_API_BASE@' \
+		--attribute=MAN_SECTION_CFG_BASE='@MAN_SECTION_CFG_BASE@' \
+		--attribute=MAN_SECTION_CMD_SYS_BASE='@MAN_SECTION_CMD_SYS_BASE@' \
+		--attribute=MAN_SECTION_CMD_USR_BASE='@MAN_SECTION_CMD_USR_BASE@' \
+		--attribute=NUT_WEBSITE_BASE='@NUT_WEBSITE_BASE@' \
 		-o "$${A2X_OUTDIR}/$(@F)" '$<' || RES=$$? ; \
 	 $(DOCBUILD_END) ; exit $$RES
 
 ### Prior to Asciidoc ~8.6.8, the --destination-dir flag didn't seem to affect the location of the intermediate .xml file.
 ### This parameter is currently required; see docs/Makefile.am for more detail.
 A2X_MANPAGE_OPTS = --doctype manpage --format manpage $${A2X_VERBOSE} \
 	--xsltproc-opts="--nonet" \
-	--attribute mansource="Network UPS Tools" \
-	--attribute manversion="@PACKAGE_VERSION@" \
-	--attribute manmanual="NUT Manual" \
-	--attribute srcdir="$(abs_srcdir)/" \
-	--attribute builddir="$(abs_builddir)/" \
-	--attribute top_srcdir="$(abs_top_srcdir)/" \
-	--attribute top_builddir="$(abs_top_builddir)/" \
+	--attribute=mansource="Network UPS Tools" \
+	--attribute=manversion="@PACKAGE_VERSION@" \
+	--attribute=manmanual="NUT Manual" \
+	--attribute=srcdir="$(abs_srcdir)/" \
+	--attribute=builddir="$(abs_builddir)/" \
+	--attribute=top_srcdir="$(abs_top_srcdir)/" \
+	--attribute=top_builddir="$(abs_top_builddir)/" \
 	--destination-dir="$${A2X_OUTDIR}"
 
 .txt-prepped.$(MAN_SECTION_CMD_USR):
@@ -1284,9 +1304,11 @@ $(abs_top_builddir)/docs/man/.prep-src-docs: $(PREP_SRC)
 	                fi ;; \
 	        esac ; \
 	        if $$MAN_SECTIONS_DEFAULT ; then \
-	            cat ; \
+	            sed \
+	                -e 's,\(home page:\) https://www.networkupstools.org/*$$,\1 @NUT_WEBSITE_BASE@/,' ; \
 	        else \
 	            sed \
+	                -e 's,\(home page:\) https://www.networkupstools.org/*$$,\1 @NUT_WEBSITE_BASE@/,' \
 	                -e 's,\(linkman:[^ []*\[\)3\],\1$(MAN_SECTION_API)],g' \
 	                -e 's,\(linkman:[^ []*\[\)5\],\1$(MAN_SECTION_CFG)],g' \
 	                -e 's,\(linkman:[^ []*\[\)8\],\1$(MAN_SECTION_CMD_SYS)],g' \
@@ -1341,9 +1363,11 @@ $(abs_top_builddir)/docs/man/.prep-src-docs: $(PREP_SRC)
 	            grep -w linkman "$${linkroot}/$${F}" > /dev/null || IS_TEXT=false ; \
 	        fi ; \
 	        if $$MAN_SECTIONS_DEFAULT || ! $$IS_TEXT ; then \
-	            cat ; \
+	            sed \
+	                -e 's,\(home page:\) https://www.networkupstools.org/*$$,\1 @NUT_WEBSITE_BASE@/,' ; \
 	        else \
 	            sed \
+	                -e 's,\(home page:\) https://www.networkupstools.org/*$$,\1 @NUT_WEBSITE_BASE@/,' \
 	                -e 's,\(linkman:[^ []*\[\)3\],\1$(MAN_SECTION_API)],g' \
 	                -e 's,\(linkman:[^ []*\[\)5\],\1$(MAN_SECTION_CFG)],g' \
 	                -e 's,\(linkman:[^ []*\[\)8\],\1$(MAN_SECTION_CMD_SYS)],g' \

docs/man/nut_usb_addvars.txt

@@ -147,4 +147,6 @@ of the library, see e.g.:
 ///////////////////
 // EDITOR NOTE: There are no backslashes in the URL above, just that
 // asciidoc sees them as "emphasis" markup, they had to be escaped.
+// If a link from this asciidoc source file is needed, please visit:
+// https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html
 ///////////////////

docs/man/ups.conf.txt

@@ -204,6 +204,8 @@ version of the library, see e.g.:
 ///////////////////
 // EDITOR NOTE: There are no backslashes in the URL above, just that
 // asciidoc sees them as "emphasis" markup, they had to be escaped.
+// If a link from this asciidoc source file is needed, please visit:
+// https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html
 ///////////////////
 
 UPS FIELDS
@@ -415,6 +417,8 @@ version of the library, see e.g.:
 ///////////////////
 // EDITOR NOTE: There are no backslashes in the URL above, just that
 // asciidoc sees them as "emphasis" markup, they had to be escaped.
+// If a link from this asciidoc source file is needed, please visit:
+// https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html
 ///////////////////
 
 INTEGRATION