Merge pull request #2366 from jimklimov/apc-modbus

Doc build recipe updates

Author: jimklimov

Makefile.am

@@ -9,11 +9,13 @@
 @NUT_AM_MAKE_CAN_EXPORT@@NUT_AM_EXPORT_CCACHE_PATH@export CCACHE_PATH=@CCACHE_PATH@
 @NUT_AM_MAKE_CAN_EXPORT@@NUT_AM_EXPORT_CCACHE_PATH@export PATH=@PATH_DURING_CONFIGURE@
 
-# First target defines default behavior: all
+# First target often defines default behavior: all
 # We follow up with another pass to `make doc` because our wild recipes
 # sometimes preclude generating all of them on the first pass (FIXME!)
-# missing e.g. PDF and HTML which then pop up in `make check` footprint.
-all: all-recursive
+# missing e.g. PDF and HTML which then pop up in `make check` footprint,
+# or misses a .prep-src-docs stage needed to pattern-make man page files
+# with some "make" implementations...
+all all-am-local all-local: doc all-recursive
 	+@$(MAKE) $(AM_MAKEFLAGS) doc
 
 # include directory for aclocal
@@ -148,7 +150,7 @@ distclean-local:
 spellcheck spellcheck-interactive:
 	+@RES=0; \
 	(cd $(builddir)/docs && $(MAKE) $(AM_MAKEFLAGS) -s $(abs_top_builddir)/docs/.prep-src-docs) || RES=$$? ; \
-	(cd $(builddir)/docs/man && $(MAKE) $(AM_MAKEFLAGS) -s $(abs_top_builddir)/docs/.prep-src-docs) || RES=$$? ; \
+	(cd $(builddir)/docs/man && $(MAKE) $(AM_MAKEFLAGS) -s $(abs_top_builddir)/docs/man/.prep-src-docs) || RES=$$? ; \
 	(cd $(builddir)/docs && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
 	(cd $(builddir)/docs/man && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
 	(cd $(builddir)/conf && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
@@ -175,10 +177,12 @@ spellcheck spellcheck-interactive:
 doc spellcheck-sortdict \
 all-docs check-docs \
 man all-man man-man check-man man-html all-html:
-	+cd $(builddir)/docs && $(MAKE) $(AM_MAKEFLAGS) $@
+	+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) $@
 
 INSTALL.nut UPGRADING NEWS README:
-	+cd $(builddir)/docs && $(MAKE) $(AM_MAKEFLAGS) ../$(@F).adoc-parsed && cp -f ../$(@F).adoc-parsed ../$(@F)
+	+cd $(abs_top_builddir)/docs && $(MAKE) $(AM_MAKEFLAGS) ../$(@F).adoc-parsed && cp -f ../$(@F).adoc-parsed ../$(@F)
 
 # Workarounds for https://github.com/github/markup/issues/1095
 # require direct definition of our attributes in each source

NEWS.adoc

@@ -221,6 +221,12 @@ https://github.com/networkupstools/nut/milestone/10
    known deficiencies in Windows platform support, as well as some un-awareness
    about configuration key words which appeared in NUT since 2013. [#2290]
 
+ - The `tools/gitlog2changelog.py.in` script was revised, in particular to
+   convert section titles (with contributor names coming from Git metadata)
+   into plain ASCII character set, for `dblatex` versions which do not allow
+   diacritics and other kinds of non-trivial characters in sections. This can
+   cause successful builds of `ChangeLog.pdf` file on more platforms, but at
+   expense of a semi-cosmetic difference in those names. [PR #2360, PR #2366]
 
 Release notes for NUT 2.8.1 - what's new since 2.8.0
 ----------------------------------------------------

UPGRADING.adoc

@@ -44,6 +44,13 @@ Changes from 2.8.1 to 2.8.2
   appear as comments, or enabled by specifying the `-U` command-line
   option several times. [#2221]
 
+- The `tools/gitlog2changelog.py.in` script was revised, in particular to
+  convert section titles (with contributor names) into plain ASCII character
+  set, for `dblatex` versions which do not allow diacritics and other kinds
+  of non-trivial characters in sections. A number of other projects seem to
+  use the NUT version of the script, and are encouraged to look at related
+  changes in `configure.ac` and `Makefile.am` recipes. [PR #2360, PR #2366]
+
 Changes from 2.8.0 to 2.8.1
 ---------------------------
 

docs/Makefile.am

@@ -131,6 +131,7 @@ endif WITH_SPELLCHECK
 check-local: $(CHECK_LOCAL_TARGETS)
 
 # Make sure sources are there for out-of-tree builds:
+all-local all-am-local \
 @DOC_BUILD_LIST@ $(ASCIIDOC_PDF) $(ASCIIDOC_HTML_SINGLE) $(ASCIIDOC_HTML_CHUNKED): $(abs_top_builddir)/docs/.prep-src-docs
 
 # This list is defined by configure script choices and options:
@@ -185,10 +186,10 @@ check-html-chunked: $(ASCIIDOC_HTML_CHUNKED)
 # 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:
-	+cd $(top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile $@
+	+cd $(abs_top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile $@
 
 man:
-	+cd $(top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile all
+	+cd $(abs_top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile all
 
 CLEANFILES = *.xml *.html *.pdf *-spellchecked docbook-xsl.css docinfo.xml.in.tmp
 CLEANFILES += $(top_builddir)/INSTALL.nut $(top_builddir)/UPGRADING $(top_builddir)/NEWS $(top_builddir)/ChangeLog.adoc $(top_builddir)/README

docs/man/Makefile.am

@@ -22,6 +22,8 @@ EGREP = grep -E
 
 all:
 
+all-am-local all-local: $(abs_top_builddir)/docs/man/.prep-src-docs
+
 # Base configuration and client manpages, always installed
 SRC_CONF_PAGES = \
 	nut.conf.txt \

tools/gitlog2changelog.py.in

@@ -12,8 +12,15 @@ import subprocess
 
 # Python 3 compatibility hack
 try:
+    try:
+        import unicode
+    except:
+        # Maybe built-in?
+        pass
     unicode('')
-except NameError:
+except NameError as ex:
+    #DEBUG# sys.stderr.write("Using 'str' as 'unicode': %s\n" % str(ex))
+    #DEBUG# sys.stderr.flush()
     unicode = str
 
 try:
@@ -125,8 +132,8 @@ for line in fin:
             author = author[0 : len(author) - fin_chop]
             if authorMustBeASCII:
                 try:
-                    if isinstance(author, str):
-                        author = unicodedata.normalize(u'NFKD', unicode(author, "UTF=8")).encode('ascii', 'ignore').decode('utf8')
+                    if isinstance(author, str) and unicode != str:
+                        author = unicodedata.normalize(u'NFKD', unicode(author, "utf-8")).encode('ascii', 'ignore').decode('utf8')
                     else:
                         author = unicodedata.normalize(u'NFKD', author).encode('ascii', 'ignore').decode('utf8')
                 except Exception as e: