[PATCH] doc: update references to renamed AsciiDoc files

[PATCH] doc: update references to renamed AsciiDoc files

[Jouke Witteveen via GitGitGadget]

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

The .txt extensions were changed to .adoc in 1f010d6 (doc: use .adoc
extension for AsciiDoc files, 2025-01-20). References to the renamed
files were not updated yet.

Signed-off-by: Jouke Witteveen <j.witteveen@gmail.com>
---
    doc: update references to renamed AsciiDoc files

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1971%2Fjoukewitteveen%2Frenamed-files-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1971/joukewitteveen/renamed-files-v1
Pull-Request: https://github.com/git/git/pull/1971

 Documentation/gitprotocol-v2.adoc          | 4 ++--
 Documentation/technical/build-systems.adoc | 2 +-
 contrib/subtree/README                     | 2 +-
 mergetools/vimdiff                         | 4 ++--
 sub-process.h                              | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)

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.
 
 Git Transport
@@ -99,7 +99,7 @@ Uses the `--http-backend-info-refs` option to
 linkgit:git-upload-pack[1].
 
 The server may need to be configured to pass this header's contents via
-the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`.
+the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.adoc`.
 
 Capability Advertisement
 ------------------------
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].
 
 === Auto-detection of supported features
 
diff --git a/contrib/subtree/README b/contrib/subtree/README
index c686b4a69b12..65d167b678c8 100644
--- a/contrib/subtree/README
+++ b/contrib/subtree/README
@@ -1,5 +1,5 @@
 
-Please read git-subtree.txt for documentation.
+Please read git-subtree.adoc for documentation.
 
 Please don't contact me using github mail; it's slow, ugly, and worst of
 all, redundant. Email me instead at apenwarr@gmail.com and I'll be happy to
diff --git a/mergetools/vimdiff b/mergetools/vimdiff
index ffc9be86c83d..8fca3a2a2fda 100644
--- a/mergetools/vimdiff
+++ b/mergetools/vimdiff
@@ -274,8 +274,8 @@ gen_cmd () {
 	# definition.
 	#
 	# The syntax of the "layout definitions" is explained in "Documentation/
-	# mergetools/vimdiff.txt" but you can already intuitively understand how
-	# it works by knowing that...
+	# mergetools/vimdiff.adoc" but you can already intuitively understand
+	# how it works by knowing that...
 	#
 	#   * "+" means "a new vim tab"
 	#   * "/" means "a new vim horizontal split"
diff --git a/sub-process.h b/sub-process.h
index 6a61638a8ace..bfc3959a1b48 100644
--- a/sub-process.h
+++ b/sub-process.h
@@ -73,7 +73,7 @@ static inline struct child_process *subprocess_get_child_process(
 
 /*
  * Perform the version and capability negotiation as described in the
- * "Handshake" section of long-running-process-protocol.txt using the
+ * "Handshake" section of long-running-process-protocol.adoc using the
  * given requested versions and capabilities. The "versions" and "capabilities"
  * parameters are arrays terminated by a 0 or blank struct.
  *

base-commit: d50a5e8939abfc07c2ff97ae72e9330939b36ee0
-- 
gitgitgadget

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

[Junio C Hamano]

"Jouke Witteveen via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Jouke Witteveen <j.witteveen@gmail.com>
>
> The .txt extensions were changed to .adoc in 1f010d6 (doc: use .adoc
> extension for AsciiDoc files, 2025-01-20). References to the renamed
> files were not updated yet.

Good spotting.  But ...

> Signed-off-by: Jouke Witteveen <j.witteveen@gmail.com>
> ---
>     doc: update references to renamed AsciiDoc files
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1971%2Fjoukewitteveen%2Frenamed-files-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1971/joukewitteveen/renamed-files-v1
> Pull-Request: https://github.com/git/git/pull/1971
>
>  Documentation/gitprotocol-v2.adoc          | 4 ++--
>  Documentation/technical/build-systems.adoc | 2 +-
>  contrib/subtree/README                     | 2 +-
>  mergetools/vimdiff                         | 4 ++--
>  sub-process.h                              | 2 +-
>  5 files changed, 7 insertions(+), 7 deletions(-)
>
> 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.

>  The server may need to be configured to pass this header's contents via
> -the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`.
> +the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.adoc`.

Ditto.  These are specifically so true because ...

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

>  === Auto-detection of supported features
>  
> diff --git a/contrib/subtree/README b/contrib/subtree/README

Old names of documentation source pages that ends with .txt outside
anything that themselves are .adoc files, like this one, unlike the
above, should be just ".txt" -> ".adoc" replacements.  Everything
below looked fine to me.

Thanks.

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

[Jouke Witteveen]

On Wed, May 21, 2025 at 9:33 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "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!

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

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

[Junio C Hamano]

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

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.