On Wed, May 21, 2025 at 9:33 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > "Jouke Witteveen via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: > > > From: Jouke Witteveen <j.witteveen@xxxxxxxxx> > > > > 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! > > 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.
