Makefile.am, docs/Makefile.am: add recipe for spellcheck-report-dict-usage to prepare a $(NUT_SPELL_DICT).usage-report [networkupstools#2402]

Facilitate maintenance of nut-website's spell checking dictionary
with words unique to the site sources.

Signed-off-by: Jim Klimov <[email protected]>

Author: jimklimov

.gitignore

@@ -50,6 +50,7 @@ Makefile.in
 /test-driver
 *-spellchecked
 *-prepped
+*.usage-report
 *.adoc-parsed
 *.adoc*.tmp
 *.txt*.tmp

Makefile.am

@@ -175,7 +175,7 @@ spellcheck spellcheck-interactive:
 # such as PDF generators, so it should only be called at developer's
 # discretion, choice and risk. The "check-man" targets covers source
 # texts, man pages and HTML rendering of man pages, as enabled by tools.
-doc spellcheck-sortdict \
+doc spellcheck-sortdict spellcheck-report-dict-usage \
 all-docs check-docs \
 man all-man man-man check-man man-html all-html:
 	+cd $(abs_top_builddir)/docs && $(MAKE) $(AM_MAKEFLAGS) -s $(abs_top_builddir)/docs/.prep-src-docs

docs/Makefile.am

@@ -88,6 +88,7 @@ ALL_TXT_SRC = nut-names.txt daisychain.txt \
  release-notes.txt ChangeLog.txt solaris-usb.txt
 
 ASPELL_FILTER_PATH = @ASPELL_FILTER_PATH@
+# NOTE: This can be set by caller such as nut-website builder:
 NUT_SPELL_DICT = nut.dict
 EXTRA_DIST += $(ALL_TXT_SRC) $(SHARED_DEPS) $(IMAGE_FILES) \
  $(IMAGE_LOGO_FILES) $(IMAGE_LOGO_FILES_JENKINS_NUT) $(CABLES_IMAGES) $(NUT_SPELL_DICT) \
@@ -145,6 +146,16 @@ all-docs: docs
 
 check-docs: check-pdf check-html-single check-html-chunked check-man
 
+# Not called by default, but handy for maintainers to check which words
+# in the custom dictionary are used or not by the current NUT codebase.
+# Note that historically many words were added to facilitate rendition
+# of the nut-website (long ago splintered from main nut repository),
+# but since recently it has a way to track its own additions to the
+# dictionary file. This code should help populate it as well, and keep
+# only relevant entries in the appropriate corner of the sources.
+# Note this can take 5-10 minutes!
+spellcheck-report-dict-usage: $(NUT_SPELL_DICT).usage-report
+
 pdf: $(ASCIIDOC_PDF)
 # also build the HTML manpages with these targets
 html-single: $(ASCIIDOC_HTML_SINGLE)
@@ -611,6 +622,41 @@ spellcheck-interactive:
 	@echo "Documentation spell check not available since 'aspell' was not found (or missing its English dictionary)."
 endif !HAVE_ASPELL
 
+# Note that NUT_SPELL_DICT may be an include snippet without the header line.
+# To exclude files like `docs/nut.dict` or `nut-website.dict(.addons)` from
+# the usage lookups, we assume that a `*.dict*` pattern fits any used names.
+# Entries prefixed with '+++' mean something used in NUT sources in context
+# that aspell is likely to treat as a word (standalone or surrounded by certain
+# chars); otherwise in entries prefixed with '---' we print hit counts and
+# contents (if any, ending with '^^^') for the character pattern across the
+# whole Git-tracked codebase (case-insensitively for good measure).
+# Note this can take 5-10 minutes!
+# TOTHINK: Constrain to (caller-specified or default) SPELLCHECK_SRC?
+$(NUT_SPELL_DICT).usage-report: $(NUT_SPELL_DICT)
+	@echo "Preparing $@"; \
+	 LANG=C; LC_ALL=C; export LANG; export LC_ALL; \
+	 grep -v -E '^personal_ws' < $? \
+	 | while read W ; do ( \
+		cd "$(abs_top_srcdir)" || exit ; \
+		git grep -q "$$W" -- ':!*.dict*' || git grep -qE "[0-9_,./\ -]$$W[0-9_,./\ -]" -- ':!*.dict*' ) \
+		&& echo "+++ $$W" \
+		|| ( \
+			HITS_CS="`git grep "$$W" -- ':!*.dict*'`" || true; \
+			HITS_CI="`git grep -i "$$W" -- ':!*.dict*'`" || true; \
+			if [ -n "$$HITS_CS" ] ; then HITC_CS="`echo "$$HITS_CS" | wc -l`" ; else HITC_CS=0; fi; \
+			if [ -n "$$HITS_CI" ] ; then HITC_CI="`echo "$$HITS_CI" | wc -l`" ; else HITC_CI=0; fi; \
+			printf '%s (%d case-sensitive/%d case-insensitive)\n' "--- $$W" "$$HITC_CS" "$$HITC_CI"; \
+			if [ "$$HITC_CS" != 0 ] ; then echo "$$HITS_CS" ; echo "^^^"; else \
+				if [ "$$HITC_CI" != 0 ] ; then echo "$$HITS_CI" ; echo "^^^"; fi; \
+			fi; \
+		); \
+	 done > "$@.tmp"
+	test -f "$@.tmp" && mv -f "$@.tmp" "$@"
+	@echo "Reporting words from $? possibly not used in current inspected code base revision under $(abs_top_srcdir)" >&2 ; \
+	 grep -E '^--- ' < "$@" | grep '(0)' || echo "SUCCESS: None found"
+
+CLEANFILES += $(NUT_SPELL_DICT).usage-report.tmp
+MAINTAINERCLEANFILES += $(NUT_SPELL_DICT).usage-report
 
 # When building out-of-tree, be sure to have all asciidoc resources
 # under the same dir structure (tool limitation)