{"thread":{"id":"63494","subject":"[PATCH] doc: update references to renamed AsciiDoc files","startedAt":"2025-05-21T19:05:13Z","lastAt":"2025-05-22T16:13:01Z","messageCount":4,"participants":["Jouke Witteveen via GitGitGadget","Junio C Hamano","Jouke Witteveen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"518605","messageId":"pull.1971.git.git.1747854310479.gitgitgadget@gmail.com","threadId":"63494","inReplyTo":null,"subject":"[PATCH] doc: update references to renamed AsciiDoc files","fromName":"Jouke Witteveen via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-21T19:05:10Z","receivedAt":"2025-05-21T19:05:13Z","isPatch":true,"sender":{"key":"j.witteveen@gmail.com","avatar":"https://avatars.githubusercontent.com/u/881703?v=4"},"body":"From: Jouke Witteveen <j.witteveen@gmail.com>\n\nThe .txt extensions were changed to .adoc in 1f010d6 (doc: use .adoc\nextension for AsciiDoc files, 2025-01-20). References to the renamed\nfiles were not updated yet.\n\nSigned-off-by: Jouke Witteveen <j.witteveen@gmail.com>\n---\n    doc: update references to renamed AsciiDoc files\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1971%2Fjoukewitteveen%2Frenamed-files-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1971/joukewitteveen/renamed-files-v1\nPull-Request: https://github.com/git/git/pull/1971\n\n Documentation/gitprotocol-v2.adoc          | 4 ++--\n Documentation/technical/build-systems.adoc | 2 +-\n contrib/subtree/README                     | 2 +-\n mergetools/vimdiff                         | 4 ++--\n sub-process.h                              | 2 +-\n 5 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/gitprotocol-v2.adoc b/Documentation/gitprotocol-v2.adoc\nindex 5598c93e67c3..abc42efcc774 100644\n--- a/Documentation/gitprotocol-v2.adoc\n+++ b/Documentation/gitprotocol-v2.adoc\n@@ -54,7 +54,7 @@ In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`.  More information can be\n found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the\n-`GIT_PROTOCOL` definition in `git.txt`. In all cases the\n+`GIT_PROTOCOL` definition in `git.adoc`. In all cases the\n response from the server is the capability advertisement.\n \n Git Transport\n@@ -99,7 +99,7 @@ Uses the `--http-backend-info-refs` option to\n linkgit:git-upload-pack[1].\n \n The server may need to be configured to pass this header's contents via\n-the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`.\n+the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.adoc`.\n \n Capability Advertisement\n ------------------------\ndiff --git a/Documentation/technical/build-systems.adoc b/Documentation/technical/build-systems.adoc\nindex d9dafb407c40..1ae2a5292f3b 100644\n--- a/Documentation/technical/build-systems.adoc\n+++ b/Documentation/technical/build-systems.adoc\n@@ -32,7 +32,7 @@ that generally have somebody running test pipelines against regularly:\n   - OpenBSD\n \n The platforms which must be supported by the tool should be aligned with our\n-[platform support policy](platform-support.txt).\n+xref:platform-support.adoc[platform support policy].\n \n === Auto-detection of supported features\n \ndiff --git a/contrib/subtree/README b/contrib/subtree/README\nindex c686b4a69b12..65d167b678c8 100644\n--- a/contrib/subtree/README\n+++ b/contrib/subtree/README\n@@ -1,5 +1,5 @@\n \n-Please read git-subtree.txt for documentation.\n+Please read git-subtree.adoc for documentation.\n \n Please don't contact me using github mail; it's slow, ugly, and worst of\n all, redundant. Email me instead at apenwarr@gmail.com and I'll be happy to\ndiff --git a/mergetools/vimdiff b/mergetools/vimdiff\nindex ffc9be86c83d..8fca3a2a2fda 100644\n--- a/mergetools/vimdiff\n+++ b/mergetools/vimdiff\n@@ -274,8 +274,8 @@ gen_cmd () {\n \t# definition.\n \t#\n \t# The syntax of the \"layout definitions\" is explained in \"Documentation/\n-\t# mergetools/vimdiff.txt\" but you can already intuitively understand how\n-\t# it works by knowing that...\n+\t# mergetools/vimdiff.adoc\" but you can already intuitively understand\n+\t# how it works by knowing that...\n \t#\n \t#   * \"+\" means \"a new vim tab\"\n \t#   * \"/\" means \"a new vim horizontal split\"\ndiff --git a/sub-process.h b/sub-process.h\nindex 6a61638a8ace..bfc3959a1b48 100644\n--- a/sub-process.h\n+++ b/sub-process.h\n@@ -73,7 +73,7 @@ static inline struct child_process *subprocess_get_child_process(\n \n /*\n  * Perform the version and capability negotiation as described in the\n- * \"Handshake\" section of long-running-process-protocol.txt using the\n+ * \"Handshake\" section of long-running-process-protocol.adoc using the\n  * given requested versions and capabilities. The \"versions\" and \"capabilities\"\n  * parameters are arrays terminated by a 0 or blank struct.\n  *\n\nbase-commit: d50a5e8939abfc07c2ff97ae72e9330939b36ee0\n-- \ngitgitgadget\n"},{"id":"518608","messageId":"xmqqr00hahdt.fsf@gitster.g","threadId":"63494","inReplyTo":"pull.1971.git.git.1747854310479.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: update references to renamed AsciiDoc files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-21T19:33:18Z","receivedAt":"2025-05-21T19:33:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jouke Witteveen via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Jouke Witteveen <j.witteveen@gmail.com>\n>\n> The .txt extensions were changed to .adoc in 1f010d6 (doc: use .adoc\n> extension for AsciiDoc files, 2025-01-20). References to the renamed\n> files were not updated yet.\n\nGood spotting.  But ...\n\n> Signed-off-by: Jouke Witteveen <j.witteveen@gmail.com>\n> ---\n>     doc: update references to renamed AsciiDoc files\n>\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1971%2Fjoukewitteveen%2Frenamed-files-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1971/joukewitteveen/renamed-files-v1\n> Pull-Request: https://github.com/git/git/pull/1971\n>\n>  Documentation/gitprotocol-v2.adoc          | 4 ++--\n>  Documentation/technical/build-systems.adoc | 2 +-\n>  contrib/subtree/README                     | 2 +-\n>  mergetools/vimdiff                         | 4 ++--\n>  sub-process.h                              | 2 +-\n>  5 files changed, 7 insertions(+), 7 deletions(-)\n>\n> diff --git a/Documentation/gitprotocol-v2.adoc b/Documentation/gitprotocol-v2.adoc\n> index 5598c93e67c3..abc42efcc774 100644\n> --- a/Documentation/gitprotocol-v2.adoc\n> +++ b/Documentation/gitprotocol-v2.adoc\n> @@ -54,7 +54,7 @@ In general a client can request to speak protocol v2 by sending\n>  `version=2` through the respective side-channel for the transport being\n>  used which inevitably sets `GIT_PROTOCOL`.  More information can be\n>  found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the\n> -`GIT_PROTOCOL` definition in `git.txt`. In all cases the\n> +`GIT_PROTOCOL` definition in `git.adoc`. In all cases the\n>  response from the server is the capability advertisement.\n\n... shouldn't this reference be also linkgit:git[1] just like the\ntwo references on the previous line?  Given that such a correction\nneeds to be made on exactly the same line, I wonder if we want to do\nthe change we see here, which stops at an in-between state, rather\nthan going to the end game of using linkgit: properly.\n\n>  The server may need to be configured to pass this header's contents via\n> -the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`.\n> +the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.adoc`.\n\nDitto.  These are specifically so true because ...\n\n> diff --git a/Documentation/technical/build-systems.adoc b/Documentation/technical/build-systems.adoc\n> index d9dafb407c40..1ae2a5292f3b 100644\n> --- a/Documentation/technical/build-systems.adoc\n> +++ b/Documentation/technical/build-systems.adoc\n> @@ -32,7 +32,7 @@ that generally have somebody running test pipelines against regularly:\n>    - OpenBSD\n>  \n>  The platforms which must be supported by the tool should be aligned with our\n> -[platform support policy](platform-support.txt).\n> +xref:platform-support.adoc[platform support policy].\n\n... this one did not stop at \"txt\" -> \"adoc\" replacement, but\nattempts to make a proper link.\n\n    Side note: I do not think we are using an explicit xref: syntax\n    in our documentation anywhere; have you checked how this gets\n    rendered?\n\n>  === Auto-detection of supported features\n>  \n> diff --git a/contrib/subtree/README b/contrib/subtree/README\n\nOld names of documentation source pages that ends with .txt outside\nanything that themselves are .adoc files, like this one, unlike the\nabove, should be just \".txt\" -> \".adoc\" replacements.  Everything\nbelow looked fine to me.\n\nThanks.\n"},{"id":"518654","messageId":"CAJ2ouazRuF8CGddobgV=xJr8=1RQ4Pv8+ndH0E4qxk-gJhG4AQ@mail.gmail.com","threadId":"63494","inReplyTo":"xmqqr00hahdt.fsf@gitster.g","subject":"Re: [PATCH] doc: update references to renamed AsciiDoc files","fromName":"Jouke Witteveen","fromEmail":"j.witteveen@gmail.com","sentAt":"2025-05-22T09:23:29Z","receivedAt":"2025-05-22T09:23:42Z","isPatch":true,"sender":{"key":"j.witteveen@gmail.com","avatar":"https://avatars.githubusercontent.com/u/881703?v=4"},"body":"On Wed, May 21, 2025 at 9:33 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> \"Jouke Witteveen via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n> > From: Jouke Witteveen <j.witteveen@gmail.com>\n> >\n> > diff --git a/Documentation/gitprotocol-v2.adoc b/Documentation/gitprotocol-v2.adoc\n> > index 5598c93e67c3..abc42efcc774 100644\n> > --- a/Documentation/gitprotocol-v2.adoc\n> > +++ b/Documentation/gitprotocol-v2.adoc\n> > @@ -54,7 +54,7 @@ In general a client can request to speak protocol v2 by sending\n> >  `version=2` through the respective side-channel for the transport being\n> >  used which inevitably sets `GIT_PROTOCOL`.  More information can be\n> >  found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the\n> > -`GIT_PROTOCOL` definition in `git.txt`. In all cases the\n> > +`GIT_PROTOCOL` definition in `git.adoc`. In all cases the\n> >  response from the server is the capability advertisement.\n>\n> ... shouldn't this reference be also linkgit:git[1] just like the\n> two references on the previous line?  Given that such a correction\n> needs to be made on exactly the same line, I wonder if we want to do\n> the change we see here, which stops at an in-between state, rather\n> than going to the end game of using linkgit: properly.\n\nYeah, I should have looked a bit further and done that. I see you did\nit for me. Thanks!\n\n> > diff --git a/Documentation/technical/build-systems.adoc b/Documentation/technical/build-systems.adoc\n> > index d9dafb407c40..1ae2a5292f3b 100644\n> > --- a/Documentation/technical/build-systems.adoc\n> > +++ b/Documentation/technical/build-systems.adoc\n> > @@ -32,7 +32,7 @@ that generally have somebody running test pipelines against regularly:\n> >    - OpenBSD\n> >\n> >  The platforms which must be supported by the tool should be aligned with our\n> > -[platform support policy](platform-support.txt).\n> > +xref:platform-support.adoc[platform support policy].\n>\n> ... this one did not stop at \"txt\" -> \"adoc\" replacement, but\n> attempts to make a proper link.\n>\n>     Side note: I do not think we are using an explicit xref: syntax\n>     in our documentation anywhere; have you checked how this gets\n>     rendered?\n>\n\nTurns out I was too lazy and blindly replaced what I recognized as a\nMarkdown link to the appropriate AsciiDoc link. However, the\ninter-document xref functionality is unavailable in the legacy\nAsciiDoc processor (`asciidoc`) and is disabled in Asciidoctor by our\nuse of `--atribute compat-mode`. I'm not sure what the right course of\naction is now. The old link was wrong, but the suggested change only\nstarts working when we drop support for `asciidoc` :-(.\n\nSorry to introduce more worries than fixing.\n"},{"id":"518669","messageId":"xmqq34cw7hf8.fsf@gitster.g","threadId":"63494","inReplyTo":"CAJ2ouazRuF8CGddobgV=xJr8=1RQ4Pv8+ndH0E4qxk-gJhG4AQ@mail.gmail.com","subject":"Re: [PATCH] doc: update references to renamed AsciiDoc files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-22T16:12:59Z","receivedAt":"2025-05-22T16:13:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jouke Witteveen <j.witteveen@gmail.com> writes:\n\n>> >  The platforms which must be supported by the tool should be aligned with our\n>> > -[platform support policy](platform-support.txt).\n>> > +xref:platform-support.adoc[platform support policy].\n>>\n>> ... this one did not stop at \"txt\" -> \"adoc\" replacement, but\n>> attempts to make a proper link.\n>>\n>>     Side note: I do not think we are using an explicit xref: syntax\n>>     in our documentation anywhere; have you checked how this gets\n>>     rendered?\n>>\n>\n> Turns out I was too lazy and blindly replaced what I recognized as a\n> Markdown link to the appropriate AsciiDoc link. However, the\n> inter-document xref functionality is unavailable in the legacy\n> AsciiDoc processor (`asciidoc`) and is disabled in Asciidoctor by our\n> use of `--atribute compat-mode`. I'm not sure what the right course of\n> action is now. The old link was wrong, but the suggested change only\n> starts working when we drop support for `asciidoc` :-(.\n\nPerhaps let the sleeping dog lie for now by doing \"txt\" -> \"adoc\"\nonly, with a bit of comment why we are not doing xref: yet next to\nit, perhaps like:\n\ndiff --git c/Documentation/technical/build-systems.adoc w/Documentation/technical/build-systems.adoc\nindex d9dafb407c..3c5237b9fd 100644\n--- c/Documentation/technical/build-systems.adoc\n+++ w/Documentation/technical/build-systems.adoc\n@@ -32,7 +32,10 @@ that generally have somebody running test pipelines against regularly:\n   - OpenBSD\n \n The platforms which must be supported by the tool should be aligned with our\n-[platform support policy](platform-support.txt).\n+platform support policy (see platform-support.adoc).\n+// once we lose AsciiDoc compatibility, we can start writing the above as:\n+// xref:platform-support.adoc#platform-support-policy[platform support policy]\n+// or something like that, but until then....\n \n === Auto-detection of supported features\n \n\nThanks.\n"}]}