Subject: Re: [PATCH] doc: update references to renamed AsciiDoc files

From: Junio C Hamano <[email-masked]>
Date: Wed, 21 May 2025 12:33:18 -0700

"Jouke Witteveen via GitGitGadget" <[email-masked]> writes:

> From: Jouke Witteveen <[email-masked]>
>
> The .txt extensions were changed to .adoc in 1f010d6 (doc: use .adoc
> extension for AsciiDoc files, 2025-01-20). References to the renamed
> files were not updated yet.

Good spotting.  But ...

> Signed-off-by: Jouke Witteveen <[email-masked]>
> ---
>     doc: update references to renamed AsciiDoc files
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1971%2Fjoukewitteveen%2Frenamed-files-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1971/joukewitteveen/renamed-files-v1
> Pull-Request: https://github.com/git/git/pull/1971
>
>  Documentation/gitprotocol-v2.adoc          | 4 ++--
>  Documentation/technical/build-systems.adoc | 2 +-
>  contrib/subtree/README                     | 2 +-
>  mergetools/vimdiff                         | 4 ++--
>  sub-process.h                              | 2 +-
>  5 files changed, 7 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/gitprotocol-v2.adoc b/Documentation/gitprotocol-v2.adoc
> index 5598c93e67c3..abc42efcc774 100644
> --- a/Documentation/gitprotocol-v2.adoc
> +++ b/Documentation/gitprotocol-v2.adoc
> @@ -54,7 +54,7 @@ In general a client can request to speak protocol v2 by sending
>  `version=2` through the respective side-channel for the transport being
>  used which inevitably sets `GIT_PROTOCOL`.  More information can be
>  found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the
> -`GIT_PROTOCOL` definition in `git.txt`. In all cases the
> +`GIT_PROTOCOL` definition in `git.adoc`. In all cases the
>  response from the server is the capability advertisement.

... shouldn't this reference be also linkgit:git[1] just like the
two references on the previous line?  Given that such a correction
needs to be made on exactly the same line, I wonder if we want to do
the change we see here, which stops at an in-between state, rather
than going to the end game of using linkgit: properly.

>  The server may need to be configured to pass this header's contents via
> -the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`.
> +the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.adoc`.

Ditto.  These are specifically so true because ...

> diff --git a/Documentation/technical/build-systems.adoc b/Documentation/technical/build-systems.adoc
> index d9dafb407c40..1ae2a5292f3b 100644
> --- a/Documentation/technical/build-systems.adoc
> +++ b/Documentation/technical/build-systems.adoc
> @@ -32,7 +32,7 @@ that generally have somebody running test pipelines against regularly:
>    - OpenBSD
>  
>  The platforms which must be supported by the tool should be aligned with our
> -[platform support policy](platform-support.txt).
> +xref:platform-support.adoc[platform support policy].

... this one did not stop at "txt" -> "adoc" replacement, but
attempts to make a proper link.

    Side note: I do not think we are using an explicit xref: syntax
    in our documentation anywhere; have you checked how this gets
    rendered?

>  === Auto-detection of supported features
>  
> diff --git a/contrib/subtree/README b/contrib/subtree/README

Old names of documentation source pages that ends with .txt outside
anything that themselves are .adoc files, like this one, unlike the
above, should be just ".txt" -> ".adoc" replacements.  Everything
below looked fine to me.

Thanks.