Jouke Witteveen <j.witteveen@xxxxxxxxx> 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` :-(. Perhaps let the sleeping dog lie for now by doing "txt" -> "adoc" only, with a bit of comment why we are not doing xref: yet next to it, perhaps like: 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.
