doc lint: make "lint-docs" non-.PHONY

Speed up the "lint-docs" target by making it non-.PHONY. Similar to my
c234e8a0ecf (Makefile: make the "sparse" target non-.PHONY,
2021-09-23). We'll now create empty files corresponding to a
dependency graph for each of these lint scripts.

This speeds things up a bit[1], and makes the output correspond to any
in-tree changes we have:

    $ touch git-add.txt; make lint-docs; make lint-docs
        GEN cmd-list.made
        GEN doc.dep
        LINT GITLINK git-add.txt
        LINT MAN END git-add.txt
        LINT MAN SEC git-add.txt
    make: Nothing to be done for 'lint-docs'.

As with the "sparse" target changes this has a hard dependency on the
use of ".DELETE_ON_ERROR" in the Makefile, added here in
db10fc6c09f (doc: simplify Makefile using .DELETE_ON_ERROR,
2021-05-21). This method also depends on the output for us emitting
any errors on STDERR (fixed in a preceding commit), as well us these
scripts exiting with non-zero on any errors (which they were already
doing).

1.
$ git show HEAD~:Documentation/Makefile >Makefile.old
$ hyperfine --warmup 2 -L f ",.old" 'make -j1 -f Makefile{f} lint-docs'
Benchmark #1: make -j1 -f Makefile lint-docs
  Time (mean ± σ):      60.8 ms ±   1.4 ms    [User: 58.7 ms, System: 2.5 ms]
  Range (min … max):    58.9 ms …  64.0 ms    48 runs

Benchmark #2: make -j1 -f Makefile.old lint-docs
  Time (mean ± σ):      84.0 ms ±   1.5 ms    [User: 78.6 ms, System: 5.7 ms]
  Range (min … max):    81.8 ms …  87.8 ms    35 runs

Summary
  'make -j1 -f Makefile lint-docs' ran
    1.38 ± 0.04 times faster than 'make -j1 -f Makefile.old lint-docs'

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 9022d4835545cbf40c9537efa8ca9a7678e42673..1c3771e7d72f690d07f4a4ce49275a3a74709dfd 100644 (file)
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -14,4 +14,5 @@ manpage-base-url.xsl
 SubmittingPatches.txt
 tmp-doc-diff/
 GIT-ASCIIDOCFLAGS
+/.build/
 /GIT-EXCLUDED-PROGRAMS

diff --git a/Documentation/Makefile b/Documentation/Makefile
index decb77d3607ca22635757bef2f181b8a64268b67..cab4ddd84da59603a5c8b70430303c27e519d4aa 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -223,6 +223,7 @@ endif
 
 ifneq ($(findstring $(MAKEFLAGS),s),s)
 ifndef V
+       QUIET           = @
        QUIET_ASCIIDOC  = @echo '   ' ASCIIDOC $@;
        QUIET_XMLTO     = @echo '   ' XMLTO $@;
        QUIET_DB2TEXI   = @echo '   ' DB2TEXI $@;
@@ -230,11 +231,15 @@ ifndef V
        QUIET_DBLATEX   = @echo '   ' DBLATEX $@;
        QUIET_XSLTPROC  = @echo '   ' XSLTPROC $@;
        QUIET_GEN       = @echo '   ' GEN $@;
-       QUIET_LINT      = @echo '   ' LINT $@;
        QUIET_STDERR    = 2> /dev/null
        QUIET_SUBDIR0   = +@subdir=
        QUIET_SUBDIR1   = ;$(NO_SUBDIR) echo '   ' SUBDIR $$subdir; \
                          $(MAKE) $(PRINT_DIR) -C $$subdir
+
+       QUIET_LINT_GITLINK      = @echo '   ' LINT GITLINK $<;
+       QUIET_LINT_MANSEC       = @echo '   ' LINT MAN SEC $<;
+       QUIET_LINT_MANEND       = @echo '   ' LINT MAN END $<;
+
        export V
 endif
 endif
@@ -344,6 +349,7 @@ GIT-ASCIIDOCFLAGS: FORCE
             fi
 
 clean:
+       $(RM) -rf .build/
        $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
        $(RM) *.texi *.texi+ *.texi++ git.info gitman.info
        $(RM) *.pdf
@@ -478,14 +484,61 @@ quick-install-html: require-htmlrepo
 print-man1:
        @for i in $(MAN1_TXT); do echo $$i; done
 
-lint-docs::
-       $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \
+## Lint: Common
+.build:
+       $(QUIET)mkdir $@
+.build/lint-docs: | .build
+       $(QUIET)mkdir $@
+
+## Lint: gitlink
+.build/lint-docs/gitlink: | .build/lint-docs
+       $(QUIET)mkdir $@
+.build/lint-docs/gitlink/howto: | .build/lint-docs
+       $(QUIET)mkdir $@
+.build/lint-docs/gitlink/config: | .build/lint-docs
+       $(QUIET)mkdir $@
+LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
+$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink
+$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/howto
+$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/config
+$(LINT_DOCS_GITLINK): lint-gitlink.perl
+$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
+       $(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \
+               $< \
                $(HOWTO_TXT) $(DOC_DEP_TXT) \
                --section=1 $(MAN1_TXT) \
                --section=5 $(MAN5_TXT) \
-               --section=7 $(MAN7_TXT) && \
-       $(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT) && \
-       $(PERL_PATH) lint-man-section-order.perl $(MAN_TXT)
+               --section=7 $(MAN7_TXT) >$@
+.PHONY: lint-docs-gitlink
+lint-docs-gitlink: $(LINT_DOCS_GITLINK)
+
+## Lint: man-end-blurb
+.build/lint-docs/man-end-blurb: | .build/lint-docs
+       $(QUIET)mkdir $@
+LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
+$(LINT_DOCS_MAN_END_BLURB): | .build/lint-docs/man-end-blurb
+$(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl
+$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt
+       $(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@
+.PHONY: lint-docs-man-end-blurb
+lint-docs-man-end-blurb: $(LINT_DOCS_MAN_END_BLURB)
+
+## Lint: man-section-order
+.build/lint-docs/man-section-order: | .build/lint-docs
+       $(QUIET)mkdir $@
+LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
+$(LINT_DOCS_MAN_SECTION_ORDER): | .build/lint-docs/man-section-order
+$(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl
+$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt
+       $(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@
+.PHONY: lint-docs-man-section-order
+lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER)
+
+## Lint: list of targets above
+.PHONY: lint-docs
+lint-docs: lint-docs-gitlink
+lint-docs: lint-docs-man-end-blurb
+lint-docs: lint-docs-man-section-order
 
 ifeq ($(wildcard po/Makefile),po/Makefile)
 doc-l10n install-l10n::

diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
index 076701ccfac478681b22caf6f739c125e8e0bdc3..1c61dd9512b9e3db1768416ede49686020d38662 100755 (executable)
--- a/Documentation/lint-gitlink.perl
+++ b/Documentation/lint-gitlink.perl
@@ -5,11 +5,12 @@ use warnings;
 
 # Parse arguments, a simple state machine for input like:
 #
-# howto/*.txt config/*.txt --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]
+# <file-to-check.txt> <valid-files-to-link-to> --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]
 my %TXT;
 my %SECTION;
 my $section;
 my $lint_these = 0;
+my $to_check = shift @ARGV;
 for my $arg (@ARGV) {
        if (my ($sec) = $arg =~ /^--section=(\d+)$/s) {
                $section = $sec;
@@ -36,7 +37,8 @@ sub report {
 }
 
 @ARGV = sort values %TXT;
-die "BUG: Nothing to process!" unless @ARGV;
+die "BUG: No list of valid linkgit:* files given" unless @ARGV;
+@ARGV = $to_check;
 while (<>) {
        my $line = $_;
        while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) {