@matheusbsbs / matheus-bagliano / commits / 2dd100c513

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>

Patrick Steinhardt committed Jun 6, 2024 at 10:01 UTC 2dd100c5139c164ce4f86734daec522a8236982e
3 files changed +87 -36
Documentation/Makefile
+4
@@ -485,12 +485,16 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt
485
486 lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
487
488 +lint-docs-manpages:
489 + $(QUIET_GEN)./lint-manpages.sh
490 +
491 ## Lint: list of targets above
492 .PHONY: lint-docs
493 lint-docs: lint-docs-fsck-msgids
494 lint-docs: lint-docs-gitlink
495 lint-docs: lint-docs-man-end-blurb
496 lint-docs: lint-docs-man-section-order
497 +lint-docs: lint-docs-manpages
498
499 ifeq ($(wildcard po/Makefile),po/Makefile)
500 doc-l10n install-l10n::
Documentation/lint-manpages.sh new
+83
@@ -0,0 +1,83 @@
1 +#!/bin/sh
2 +
3 +extract_variable () {
4 + (
5 + cat ../Makefile
6 + cat <<EOF
7 +print_variable:
8 + @\$(foreach b,\$($1),echo XXX \$(b:\$X=) YYY;)
9 +EOF
10 + ) |
11 + make -C .. -f - print_variable 2>/dev/null |
12 + sed -n -e 's/.*XXX \(.*\) YYY.*/\1/p'
13 +}
14 +
15 +check_missing_docs () {
16 + for v in $ALL_COMMANDS
17 + do
18 + case "$v" in
19 + git-merge-octopus) continue;;
20 + git-merge-ours) continue;;
21 + git-merge-recursive) continue;;
22 + git-merge-resolve) continue;;
23 + git-merge-subtree) continue;;
24 + git-fsck-objects) continue;;
25 + git-init-db) continue;;
26 + git-remote-*) continue;;
27 + git-stage) continue;;
28 + git-legacy-*) continue;;
29 + git-?*--?* ) continue ;;
30 + esac
31 +
32 + if ! test -f "$v.txt"
33 + then
34 + echo "no doc: $v"
35 + fi
36 +
37 + if ! sed -e '1,/^### command list/d' -e '/^#/d' ../command-list.txt |
38 + grep -q "^$v[ ]"
39 + then
40 + case "$v" in
41 + git)
42 + ;;
43 + *)
44 + echo "no link: $v";;
45 + esac
46 + fi
47 + done
48 +}
49 +
50 +check_extraneous_docs () {
51 + (
52 + sed -e '1,/^### command list/d' \
53 + -e '/^#/d' \
54 + -e '/guide$/d' \
55 + -e '/interfaces$/d' \
56 + -e 's/[ ].*//' \
57 + -e 's/^/listed /' ../command-list.txt
58 + make print-man1 |
59 + grep '\.txt$' |
60 + sed -e 's|^|documented |' \
61 + -e 's/\.txt//'
62 + ) | (
63 + all_commands="$(printf "%s " "$ALL_COMMANDS" "$BUILT_INS" "$EXCLUDED_PROGRAMS" | tr '\n' ' ')"
64 +
65 + while read how cmd
66 + do
67 + case " $all_commands " in
68 + *" $cmd "*) ;;
69 + *)
70 + echo "removed but $how: $cmd";;
71 + esac
72 + done
73 + )
74 +}
75 +
76 +BUILT_INS="$(extract_variable BUILT_INS)"
77 +ALL_COMMANDS="$(extract_variable ALL_COMMANDS)"
78 +EXCLUDED_PROGRAMS="$(extract_variable EXCLUDED_PROGRAMS)"
79 +
80 +{
81 + check_missing_docs
82 + check_extraneous_docs
83 +} | sort
Makefile
-36
@@ -3757,42 +3757,6 @@ ALL_COMMANDS += scalar
3757 .PHONY: check-docs
3758 check-docs::
3759 $(MAKE) -C Documentation lint-docs
3760 - @(for v in $(patsubst %$X,%,$(ALL_COMMANDS)); \
3761 - do \
3762 - case "$$v" in \
3763 - git-merge-octopus | git-merge-ours | git-merge-recursive | \
3764 - git-merge-resolve | git-merge-subtree | \
3765 - git-fsck-objects | git-init-db | \
3766 - git-remote-* | git-stage | git-legacy-* | \
3767 - git-?*--?* ) continue ;; \
3768 - esac ; \
3769 - test -f "Documentation/$$v.txt" || \
3770 - echo "no doc: $$v"; \
3771 - sed -e '1,/^### command list/d' -e '/^#/d' command-list.txt | \
3772 - grep -q "^$$v[ ]" || \
3773 - case "$$v" in \
3774 - git) ;; \
3775 - *) echo "no link: $$v";; \
3776 - esac ; \
3777 - done; \
3778 - ( \
3779 - sed -e '1,/^### command list/d' \
3780 - -e '/^#/d' \
3781 - -e '/guide$$/d' \
3782 - -e '/interfaces$$/d' \
3783 - -e 's/[ ].*//' \
3784 - -e 's/^/listed /' command-list.txt; \
3785 - $(MAKE) -C Documentation print-man1 | \
3786 - grep '\.txt$$' | \
3787 - sed -e 's|^|documented |' \
3788 - -e 's/\.txt//'; \
3789 - ) | while read how cmd; \
3790 - do \
3791 - case " $(patsubst %$X,%,$(ALL_COMMANDS) $(BUILT_INS) $(EXCLUDED_PROGRAMS)) " in \
3792 - *" $$cmd "*) ;; \
3793 - *) echo "removed but $$how: $$cmd" ;; \
3794 - esac; \
3795 - done ) | sort
3760
3761 ### Make sure built-ins do not have dups and listed in git.c
3762 #