Re: [PATCH v2 1/4] doc: add some missing technical documents

[Patrick Steinhardt <ps@pks.im>]

On Thu, Oct 02, 2025 at 11:12:13PM +0100, Ramsay Jones wrote:
> Commit bcf7edee09 ("meson: generate articles", 2024-12-27) added the
> generation of the 'howto' and 'technical' documents to the meson build.
> At this time those documents had a '*.txt' file extension, but they were
> renamed with an '*.adoc' extension by commit 1f010d6bdf ("doc: use .adoc
> extension for AsciiDoc files", 2025-01-20), for the most part. For the
> meson build, commit 87eccc3a81 ("meson: fix building technical and howto
> docs", 2025-03-02) fixed the meson.build files, which had not been
> updated when the files were renamed.
> 
> However, the 'Documentation/Makefile' has not been updated to include
> all of the recently added technical documents. In particular, the
> following are built by meson, but not by the Makefile:
> 
>     commit-graph.adoc
>     directory-rename-detection.adoc
>     packfile-uri.adoc
>     remembering-renames.adoc
>     repository-version.adoc
>     rerere.adoc
>     sparse-checkout.adoc
>     sparse-index.adoc
> 
> In order to ensure that both build systems format the same technical
> documents, add the above documents to the TECH_DOCS variable in the
> Documentation/Makefile.

I was wondering whether we also want to have a change like the
following:

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6fb83d0c6e..666b0b6fbd 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -524,15 +524,20 @@ lint-docs-manpages:
 lint-docs-meson:
 	@# awk acts up when trying to match single quotes, so we use \047 instead.
 	@mkdir -p tmp-meson-diff && \
-	awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^  \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \
+	{ \
+		awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^  \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build && \
+		awk "/^articles = \[$$/ {flag=1 ; next } /^\]$$/ { flag=0 } flag { gsub(/^  \047/, \"\"); gsub(/\047,$$/, \"\"); print }" technical/meson.build; \
+	} | \
 		grep -v -e '#' -e '^$$' | \
 		sort >tmp-meson-diff/meson.adoc && \
-	ls git*.adoc scalar.adoc | \
+	ls git*.adoc scalar.adoc technical/*.adoc | \
+		xargs -n1 basename | \
 		grep -v -e git-bisect-lk2009.adoc \
 			-e git-pack-redundant.adoc \
 			-e git-tools.adoc \
 			-e git-whatchanged.adoc \
-			>tmp-meson-diff/actual.adoc && \
+			-e api-.*.adoc | \
+			sort >tmp-meson-diff/actual.adoc && \
 	if ! cmp tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; then \
 		echo "Meson man pages differ from actual man pages:"; \
 		diff -u tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; \

This builds on our existing linting rule and would catch any discrepancy
in man pages that we have in "Documentation/technical/" that isn't
listed in Meson.

This check isn't quite complete, there's two things missing:

  - We have an equivalent check in "Documentation/meson.build" that we
    might want to extend to also cover articles.

  - We don't have a check to ensure that our Makefile and Meson are in
    sync.

But regardless of that, the above check surfaces one more missing
article:

    $ make lint-docs-meson
        GEN doc.dep
    make: *** Deleting file 'doc.dep'
    tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc differ: byte 3877, line 206
    Meson man pages differ from actual man pages:
    --- tmp-meson-diff/meson.adoc	2025-10-08 08:42:49.864991169 +0200
    +++ tmp-meson-diff/actual.adoc	2025-10-08 08:42:50.072988794 +0200
    @@ -203,6 +203,7 @@
     git-worktree.adoc
     git-write-tree.adoc
     hash-function-transition.adoc
    +large-object-promisors.adoc
     long-running-process-protocol.adoc
     multi-pack-index.adoc
     packfile-uri.adoc
    make: *** [Makefile:526: lint-docs-meson] Error 1

Patrick