Re: [PATCH v2 4/3] doc: fix build-docdep.perl

From: Todd Zullinger <tmz@pobox.com>
Date: Mar 1, 2025, 19:41 UTC
Message-ID: <Z8Ni0EyQYgD8uWJ0@teonanacatl.net>
In-Reply-To: <xmqqcyf0zjzt.fsf_-_@gitster.g>

Junio C Hamano wrote:

> We renamed from .txt to .adoc all the asciidoc source files and
> necessary includes.  We also need to adjust the build-docdep tool to
> work on files whose suffix is .adoc when computing the documentation
> dependencies.

Good catch. This change looks obviously correct. Testing shows that it generates the same content as in 2.48.1, apart from 2 small changes due to adding config/trailers.adoc in the 2.49.0 cycle.

I took a look though the output of `git grep -F .txt` to see what other low-hanging and/or important fruit there was. It's a decent list, though I don't know that most of it is crucial (any more or less than imperfect documentation ever is).

Here's a "quick" list of what I noted while perusing that. I may try to fix up some of these, but I doubt I'll get to the majority of them anytime soon. Even if I or someone else did, it may not be worth the review time during the RC cycle to try?

There references to .txt in various .gitattributes files. I suspect that Documentation/.gitattributes could just be removed. It contains only `*.txt whitespace`. [It was last changed when it was added in 14f9e128d3 (Define the project whitespace policy, 2008-02-10). :)]

Other references to .txt files appear in the top-level .gitattributes which should likely be updated:

    /Documentation/git-merge.txt conflict-marker-size=32
    /Documentation/gitk.txt conflict-marker-size=32
    /Documentation/user-manual.txt conflict-marker-size=32

These were added in b9b07efdb2 (.gitattributes: add conflict-marker-size for relevant files, 2018-08-28).

The README.md, Documentation/CodingGuidelines, and Documnetation/MyFirstContribution.adoc files all reference various Documentation/*.txt paths. It's probably a little cruel to make first time contributors who are diligent enough to read the docs then stumble over outdated information. :)

Documentation/howto/new-command.adoc references api-builtin.txt, but that was removed long before the adoc renaming, in ec14d4ecb5 (builtin.h: take over documentation from api-builtin.txt, 2017-08-02).

Documentation/technical/partial-clone.adoc references Documentation/rev-list-options.txt..

Makefile references Documentation/technical/racy-git.txt.

And there are a smattering of code comments which direct folks to various Documentation/*.txt files. Those are worth fixing, but likely anyone deep in the weeks of fsck.h will be able to find their way from Documentation/fsck-msgids.txt to Documentation/fsck-msgids.adoc. ;)

Cheers,

-- 
Todd