Makefile: extract script to lint missing/extraneous manpages

The "check-docs" target of our top-level Makefile fulfills two different
roles. For one it runs the "lint-docs" target of the "Documentation/"
Makefile. And second it performs some checks of whether there are any
manpages that are missing or extraneous via some inline scripts.

The second set of checks feels quite misplaced in the top-level Makefile
as it would fit in much better with our "lint-docs" target. Back when
the checks were introduced in 8c989ec528 (Makefile: $(MAKE) check-docs,
2006-04-13), that target did not yet exist though.

Furthermore, the script makes use of several Makefile variables which
are defined in the top-level Makefile, which makes it hard to access
their contents from elsewhere. There is a trick though that we already
use in "check-builtins.sh" to gain access: we can create an ad-hoc
Makefile that has an extra target to print those variables.

Pull out the script into a separate "lint-manpages.sh" script by using
that trick. Wire up that script via the "lint-docs" target. For one,
normal shell scripts are way easier to reason about than those which are
embedded in a Makefile. Second, it allows one to easily execute the
script standalone without any of the other checks.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index a04da672c69685c3627df4c75edf1501a05f0d90..a3868a462faf4d753df4c639c7a5d8c3dfba2c33 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -485,12 +485,16 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt
 
 lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
 
+lint-docs-manpages:
+       $(QUIET_GEN)./lint-manpages.sh
+
 ## Lint: list of targets above
 .PHONY: lint-docs
 lint-docs: lint-docs-fsck-msgids
 lint-docs: lint-docs-gitlink
 lint-docs: lint-docs-man-end-blurb
 lint-docs: lint-docs-man-section-order
+lint-docs: lint-docs-manpages
 
 ifeq ($(wildcard po/Makefile),po/Makefile)
 doc-l10n install-l10n::

diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh
new file mode 100755 (executable)
index 0000000..0abb4e0
--- /dev/null
+++ b/Documentation/lint-manpages.sh
@@ -0,0 +1,83 @@
+#!/bin/sh
+
+extract_variable () {
+       (
+               cat ../Makefile
+               cat <<EOF
+print_variable:
+       @\$(foreach b,\$($1),echo XXX \$(b:\$X=) YYY;)
+EOF
+       ) |
+       make -C .. -f - print_variable 2>/dev/null |
+       sed -n -e 's/.*XXX \(.*\) YYY.*/\1/p'
+}
+
+check_missing_docs () {
+       for v in $ALL_COMMANDS
+       do
+               case "$v" in
+               git-merge-octopus) continue;;
+               git-merge-ours) continue;;
+               git-merge-recursive) continue;;
+               git-merge-resolve) continue;;
+               git-merge-subtree) continue;;
+               git-fsck-objects) continue;;
+               git-init-db) continue;;
+               git-remote-*) continue;;
+               git-stage) continue;;
+               git-legacy-*) continue;;
+               git-?*--?* ) continue ;;
+               esac
+
+               if ! test -f "$v.txt"
+               then
+                       echo "no doc: $v"
+               fi
+
+               if ! sed -e '1,/^### command list/d' -e '/^#/d' ../command-list.txt |
+                       grep -q "^$v[   ]"
+               then
+                       case "$v" in
+                       git)
+                               ;;
+                       *)
+                               echo "no link: $v";;
+                       esac
+               fi
+       done
+}
+
+check_extraneous_docs () {
+       (
+               sed -e '1,/^### command list/d' \
+                   -e '/^#/d' \
+                   -e '/guide$/d' \
+                   -e '/interfaces$/d' \
+                   -e 's/[     ].*//' \
+                   -e 's/^/listed /' ../command-list.txt
+               make print-man1 |
+               grep '\.txt$' |
+               sed -e 's|^|documented |' \
+                   -e 's/\.txt//'
+       ) | (
+               all_commands="$(printf "%s " "$ALL_COMMANDS" "$BUILT_INS" "$EXCLUDED_PROGRAMS" | tr '\n' ' ')"
+
+               while read how cmd
+               do
+                       case " $all_commands " in
+                       *" $cmd "*) ;;
+                       *)
+                               echo "removed but $how: $cmd";;
+                       esac
+               done
+       )
+}
+
+BUILT_INS="$(extract_variable BUILT_INS)"
+ALL_COMMANDS="$(extract_variable ALL_COMMANDS)"
+EXCLUDED_PROGRAMS="$(extract_variable EXCLUDED_PROGRAMS)"
+
+{
+       check_missing_docs
+       check_extraneous_docs
+} | sort

diff --git a/Makefile b/Makefile
index 59d98ba688f1780d9d49be0aced214c9c6ab58fd..84e2aa968660ed936be7e80f31806d1986a3461a 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -3757,42 +3757,6 @@ ALL_COMMANDS += scalar
 .PHONY: check-docs
 check-docs::
        $(MAKE) -C Documentation lint-docs
-       @(for v in $(patsubst %$X,%,$(ALL_COMMANDS)); \
-       do \
-               case "$$v" in \
-               git-merge-octopus | git-merge-ours | git-merge-recursive | \
-               git-merge-resolve | git-merge-subtree | \
-               git-fsck-objects | git-init-db | \
-               git-remote-* | git-stage | git-legacy-* | \
-               git-?*--?* ) continue ;; \
-               esac ; \
-               test -f "Documentation/$$v.txt" || \
-               echo "no doc: $$v"; \
-               sed -e '1,/^### command list/d' -e '/^#/d' command-list.txt | \
-               grep -q "^$$v[  ]" || \
-               case "$$v" in \
-               git) ;; \
-               *) echo "no link: $$v";; \
-               esac ; \
-       done; \
-       ( \
-               sed -e '1,/^### command list/d' \
-                   -e '/^#/d' \
-                   -e '/guide$$/d' \
-                   -e '/interfaces$$/d' \
-                   -e 's/[     ].*//' \
-                   -e 's/^/listed /' command-list.txt; \
-               $(MAKE) -C Documentation print-man1 | \
-               grep '\.txt$$' | \
-               sed -e 's|^|documented |' \
-                   -e 's/\.txt//'; \
-       ) | while read how cmd; \
-       do \
-               case " $(patsubst %$X,%,$(ALL_COMMANDS) $(BUILT_INS) $(EXCLUDED_PROGRAMS)) " in \
-               *" $$cmd "*)    ;; \
-               *) echo "removed but $$how: $$cmd" ;; \
-               esac; \
-       done ) | sort
 
 ### Make sure built-ins do not have dups and listed in git.c
 #