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

From: Jouke Witteveen <j.witteveen@gmail.com>
Date: May 22, 2025, 09:23 UTC
Message-ID: <CAJ2ouazRuF8CGddobgV=xJr8=1RQ4Pv8+ndH0E4qxk-gJhG4AQ@mail.gmail.com>
In-Reply-To: <xmqqr00hahdt.fsf@gitster.g>

On Wed, May 21, 2025 at 9:33 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 22 quoted lines

>
> "Jouke Witteveen via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Jouke Witteveen <j.witteveen@gmail.com>
> >
> > 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.

Yeah, I should have looked a bit further and done that. I see you did it for me. Thanks!

Show 18 quoted lines

> > 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?
>

Turns out I was too lazy and blindly replaced what I recognized as a Markdown link to the appropriate AsciiDoc link. However, the inter-document xref functionality is unavailable in the legacy AsciiDoc processor (`asciidoc`) and is disabled in Asciidoctor by our use of `--atribute compat-mode`. I'm not sure what the right course of action is now. The old link was wrong, but the suggested change only starts working when we drop support for `asciidoc` :-(.

Sorry to introduce more worries than fixing.