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

From

Junio C Hamano <gitster@pobox.com>

Date

May 22, 2025, 16:12 UTC

Message-ID

<xmqq34cw7hf8.fsf@gitster.g>

In-Reply-To

<CAJ2ouazRuF8CGddobgV=xJr8=1RQ4Pv8+ndH0E4qxk-gJhG4AQ@mail.gmail.com>

Jouke Witteveen <j.witteveen@gmail.com> writes:

>> >  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` :-(.

diff --git c/Documentation/technical/build-systems.adoc w/Documentation/technical/build-systems.adoc
index d9dafb407c..3c5237b9fd 100644
--- c/Documentation/technical/build-systems.adoc
+++ w/Documentation/technical/build-systems.adoc
@@ -32,7 +32,10 @@ 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).
+platform support policy (see platform-support.adoc).
+// once we lose AsciiDoc compatibility, we can start writing the above as:
+// xref:platform-support.adoc#platform-support-policy[platform support policy]
+// or something like that, but until then....
 
 === Auto-detection of supported features
 

Thanks.