threads / patch / 63019

patch, 3 partsdoc: txt -> adoc fixes

Subject: [PATCH 0/3] doc: txt -> adoc fixes

## tl;dr

22 messages between Feb 28, 2025 and Mar 1, 2025. Diffs are folded; open one to read it.

replies: 21people: 3as markdown or json

Todd Zullinger· Feb 28, 2025, 03:47 UTC · lore

I noticed broken links in the howto-index.html output of v2.49.0-rc0. This is due to the recent txt -> adoc renaming. I chose to replace the numerous occurences of "txt" with "adoc" in howto-index.sh for consistency within the script. It could be argued that only the few instances which glob '*.txt' should be changed, of course.

I also renamed the git-*.txt files in contrib/contacts and contrib/subtree while I was here. The only other file in contrib which might warrant that treatment is contrib/mw-to-git/git-remote-mediawiki.txt. I skipped it as I am not sure whether it is actively maintained anymore. If we want to rename it to be consistent, that's easy enough.

Todd Zullinger (3):
  doc: update howto-index.sh for .adoc extensions
  contrib/contacts: rename .txt to .adoc
  contrib/subtree: rename .txt to .adoc
 Documentation/howto/howto-index.sh                 | 14 +++++++-------
 contrib/contacts/Makefile                          |  2 +-
 .../{git-contacts.txt => git-contacts.adoc}        |  0
 contrib/subtree/Makefile                           |  2 +-
 .../subtree/{git-subtree.txt => git-subtree.adoc}  |  0
 5 files changed, 9 insertions(+), 9 deletions(-)
 rename contrib/contacts/{git-contacts.txt => git-contacts.adoc} (100%)
 rename contrib/subtree/{git-subtree.txt => git-subtree.adoc} (100%)
-- 
2.49.0.rc0
Todd Zullinger· Feb 28, 2025, 03:47 UTC · re: Todd Zullinger · lore

[PATCH 1/3] doc: update howto-index.sh for .adoc extensions

The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc extension for AsciiDoc files, 2025-01-20). This left broken links in the generated howto-index.html.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/howto/howto-index.sh | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)
Show changes to Documentation/howto/howto-index.sh +7 −7
diff --git a/Documentation/howto/howto-index.sh b/Documentation/howto/howto-index.sh
index eecd123a93..ace49830a8 100755
--- a/Documentation/howto/howto-index.sh
+++ b/Documentation/howto/howto-index.sh
@@ -9,9 +9,9 @@ people describing how they use Git in their workflow.
 
 EOF
 
-for txt
+for adoc
 do
-	title=$(expr "$txt" : '.*/\(.*\)\.txt$')
+	title=$(expr "$adoc" : '.*/\(.*\)\.adoc$')
 	from=$(sed -ne '
 	/^$/q
 	/^From:[ 	]/{
@@ -21,7 +21,7 @@ do
 		s/^/by /
 		p
 	}
-	' "$txt")
+	' "$adoc")
 
 	abstract=$(sed -ne '
 	/^Abstract:[ 	]/{
@@ -39,13 +39,13 @@ do
 		x
 		p
 		q
-	}' "$txt")
+	}' "$adoc")
 
-	if grep 'Content-type: text/asciidoc' >/dev/null $txt
+	if grep 'Content-type: text/asciidoc' >/dev/null $adoc
 	then
-		file=$(expr "$txt" : '\(.*\)\.txt$').html
+		file=$(expr "$adoc" : '\(.*\)\.adoc$').html
 	else
-		file="$txt"
+		file="$adoc"
 	fi
 
 	echo "* link:howto/$(basename "$file")[$title] $from

-- 
2.49.0.rc0
Junio C Hamano· Feb 28, 2025, 13:55 UTC · re: Todd Zullinger · lore

Re: [PATCH 1/3] doc: update howto-index.sh for .adoc extensions

Todd Zullinger <tmz@pobox.com> writes:
Show 43 quoted lines
> The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc
> extension for AsciiDoc files, 2025-01-20).  This left broken links in
> the generated howto-index.html.
>
> Signed-off-by: Todd Zullinger <tmz@pobox.com>
> ---
>  Documentation/howto/howto-index.sh | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/howto/howto-index.sh b/Documentation/howto/howto-index.sh
> index eecd123a93..ace49830a8 100755
> --- a/Documentation/howto/howto-index.sh
> +++ b/Documentation/howto/howto-index.sh
> @@ -9,9 +9,9 @@ people describing how they use Git in their workflow.
>  
>  EOF
>  
> -for txt
> +for adoc
>  do
> -	title=$(expr "$txt" : '.*/\(.*\)\.txt$')
> +	title=$(expr "$adoc" : '.*/\(.*\)\.adoc$')
>  	from=$(sed -ne '
>  	/^$/q
>  	/^From:[ 	]/{
> @@ -21,7 +21,7 @@ do
>  		s/^/by /
>  		p
>  	}
> -	' "$txt")
> +	' "$adoc")
>  
>  	abstract=$(sed -ne '
>  	/^Abstract:[ 	]/{
> @@ -39,13 +39,13 @@ do
>  		x
>  		p
>  		q
> -	}' "$txt")
> +	}' "$adoc")
>  
> -	if grep 'Content-type: text/asciidoc' >/dev/null $txt
> +	if grep 'Content-type: text/asciidoc' >/dev/null $adoc

This is an existing "Huh?" and should not be touched in this patch but it is somewhat inconsistent that everywhere else "$adoc" is prepared to have $IFS whitespaces in it (even though none of our files do), but this single reference is not. We may #leftoverbit want to make it consistent after the dust settles.

Show 9 quoted lines
>  	then
> -		file=$(expr "$txt" : '\(.*\)\.txt$').html
> +		file=$(expr "$adoc" : '\(.*\)\.adoc$').html
>  	else
> -		file="$txt"
> +		file="$adoc"
>  	fi
>  
>  	echo "* link:howto/$(basename "$file")[$title] $from
Looks quite sane.  Thanks.
Todd Zullinger· Feb 28, 2025, 03:47 UTC · re: Todd Zullinger · lore

[PATCH 2/3] contrib/contacts: rename .txt to .adoc

The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc extension for AsciiDoc files, 2025-01-20).

Do the same for contrib/contacts.
Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 contrib/contacts/Makefile                                | 2 +-
 contrib/contacts/{git-contacts.txt => git-contacts.adoc} | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename contrib/contacts/{git-contacts.txt => git-contacts.adoc} (100%)
Show changes to 2 files +1 −1

contrib/contacts/Makefile, contrib/contacts/git-contacts.txt

diff --git a/contrib/contacts/Makefile b/contrib/contacts/Makefile
index a2990f0dcb..9c4ca4f3bc 100644
--- a/contrib/contacts/Makefile
+++ b/contrib/contacts/Makefile
@@ -34,7 +34,7 @@ GIT_CONTACTS := git-contacts
 
 GIT_CONTACTS_DOC := git-contacts.1
 GIT_CONTACTS_XML := git-contacts.xml
-GIT_CONTACTS_TXT := git-contacts.txt
+GIT_CONTACTS_TXT := git-contacts.adoc
 GIT_CONTACTS_HTML := git-contacts.html
 
 doc: $(GIT_CONTACTS_DOC) $(GIT_CONTACTS_HTML)
diff --git a/contrib/contacts/git-contacts.txt b/contrib/contacts/git-contacts.adoc
similarity index 100%
rename from contrib/contacts/git-contacts.txt
rename to contrib/contacts/git-contacts.adoc

-- 
2.49.0.rc0
Patrick Steinhardt· Feb 28, 2025, 08:13 UTC · re: Todd Zullinger · lore

Re: [PATCH 2/3] contrib/contacts: rename .txt to .adoc

On Thu, Feb 27, 2025 at 10:47:05PM -0500, Todd Zullinger wrote:
> The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc
> extension for AsciiDoc files, 2025-01-20).
> 
> Do the same for contrib/contacts.

ef18273a2d9 (Merge branch 'ps/meson-contrib-bits' into next, 2025-02-27) wires up this thingy via Meson, so we'd also need the following change on top:

Show changes to contrib/contacts/meson.build +2 −2
diff --git a/contrib/contacts/meson.build b/contrib/contacts/meson.build
index 6ec92f47c43..73d82dfe52b 100644
--- a/contrib/contacts/meson.build
+++ b/contrib/contacts/meson.build
@@ -16,7 +16,7 @@ if get_option('docs').contains('man')
       '@INPUT@',
     ],
     depends: documentation_deps,
-    input: 'git-contacts.txt',
+    input: 'git-contacts.adoc',
     output: 'git-contacts.xml',
   )
 
@@ -47,7 +47,7 @@ if get_option('docs').contains('html')
       '@INPUT@',
     ],
     depends: documentation_deps,
-    input: 'git-contacts.txt',
+    input: 'git-contacts.adoc',
     output: 'git-contacts.html',
     install: true,
     install_dir: get_option('datadir') / 'doc/git-doc',

Patrick
Todd Zullinger· Feb 28, 2025, 13:57 UTC · re: Patrick Steinhardt · lore

Re: [PATCH 2/3] contrib/contacts: rename .txt to .adoc

Patrick Steinhardt wrote:
Show 32 quoted lines
> On Thu, Feb 27, 2025 at 10:47:05PM -0500, Todd Zullinger wrote:
>> The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc
>> extension for AsciiDoc files, 2025-01-20).
>> 
>> Do the same for contrib/contacts.
> 
> ef18273a2d9 (Merge branch 'ps/meson-contrib-bits' into next, 2025-02-27)
> wires up this thingy via Meson, so we'd also need the following change
> on top:
> 
> diff --git a/contrib/contacts/meson.build b/contrib/contacts/meson.build
> index 6ec92f47c43..73d82dfe52b 100644
> --- a/contrib/contacts/meson.build
> +++ b/contrib/contacts/meson.build
> @@ -16,7 +16,7 @@ if get_option('docs').contains('man')
>        '@INPUT@',
>      ],
>      depends: documentation_deps,
> -    input: 'git-contacts.txt',
> +    input: 'git-contacts.adoc',
>      output: 'git-contacts.xml',
>    )
>  
> @@ -47,7 +47,7 @@ if get_option('docs').contains('html')
>        '@INPUT@',
>      ],
>      depends: documentation_deps,
> -    input: 'git-contacts.txt',
> +    input: 'git-contacts.adoc',
>      output: 'git-contacts.html',
>      install: true,
>      install_dir: get_option('datadir') / 'doc/git-doc',

Since this is only in next and the first patch of the series targets a "breakage" in 2.49.0-rc0, should I split the latter commits into a separate series based on next or is ef18273a2d9 likely to be merged into master before 2.49.0?

Whatever makes things easier for Junio is the goal. :)
Thanks,
-- 
Todd
Junio C Hamano· Feb 28, 2025, 18:47 UTC · re: Todd Zullinger · lore

Re: [PATCH 2/3] contrib/contacts: rename .txt to .adoc

Todd Zullinger <tmz@pobox.com> writes:
> Since this is only in next and the first patch of the series
> targets a "breakage" in 2.49.0-rc0, should I split the
> latter commits into a separate series based on next or is
> ef18273a2d9 likely to be merged into master before 2.49.0?

ef18273a (Merge branch 'ps/meson-contrib-bits' into next, 2025-02-27) WILL NEVER be merged into master in any timeframe. Doing so will pull all the other merge commits on 'next' into 'master'.

According to tinyurl.com/gitcal, we plan to tag -rc1 on Mar 4th and -rc2 on Mar 10th. The topic ps/meson-contrib-bits will have spent 7 calendar days in 'next' before we tag -rc2, so unless people find issues with the topic while in 'next', it is expected to land before the 10th.

Creating a merge of ps/meson-contrib-bits topic into the 'master' (you do this yourself locally), and building your series on that merge commit (and you send these patches to the list, saying that they are based on such a merge in the cover letter) would be the most appropriate in this case, I think.

Thanks.
Todd Zullinger· Mar 1, 2025, 15:34 UTC · re: Junio C Hamano · lore

Re: [PATCH 2/3] contrib/contacts: rename .txt to .adoc

Junio C Hamano wrote:
Show 11 quoted lines
> Todd Zullinger <tmz@pobox.com> writes:
> 
>> Since this is only in next and the first patch of the series
>> targets a "breakage" in 2.49.0-rc0, should I split the
>> latter commits into a separate series based on next or is
>> ef18273a2d9 likely to be merged into master before 2.49.0?
> 
> ef18273a (Merge branch 'ps/meson-contrib-bits' into next,
> 2025-02-27) WILL NEVER be merged into master in any timeframe.
> Doing so will pull all the other merge commits on 'next' into
> 'master'.

Thank you for patiently correcting and explaining that. I did intend it to be as you described, rather than merging the merge commit. But I was both lazy and sloppy with my wording, unfortunately. :/

Show 11 quoted lines
> According to tinyurl.com/gitcal, we plan to tag -rc1 on Mar 4th and
> -rc2 on Mar 10th.  The topic ps/meson-contrib-bits will have spent 7
> calendar days in 'next' before we tag -rc2, so unless people find
> issues with the topic while in 'next', it is expected to land before
> the 10th.
> 
> Creating a merge of ps/meson-contrib-bits topic into the 'master'
> (you do this yourself locally), and building your series on that
> merge commit (and you send these patches to the list, saying that
> they are based on such a merge in the cover letter) would be the
> most appropriate in this case, I think.
Sounds good.  I'll send a v2 with that shape momentarily.
-- 
Todd
Todd Zullinger· Feb 28, 2025, 03:47 UTC · re: Todd Zullinger · lore

[PATCH 3/3] contrib/subtree: rename .txt to .adoc

The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc extension for AsciiDoc files, 2025-01-20).

Do the same for contrib/subtree.
Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 contrib/subtree/Makefile                              | 2 +-
 contrib/subtree/{git-subtree.txt => git-subtree.adoc} | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename contrib/subtree/{git-subtree.txt => git-subtree.adoc} (100%)
Show changes to 2 files +1 −1

contrib/subtree/Makefile, contrib/subtree/git-subtree.txt

diff --git a/contrib/subtree/Makefile b/contrib/subtree/Makefile
index 8fe0bfd401..c0c9f21cb7 100644
--- a/contrib/subtree/Makefile
+++ b/contrib/subtree/Makefile
@@ -50,7 +50,7 @@ GIT_SUBTREE    := git-subtree
 
 GIT_SUBTREE_DOC := git-subtree.1
 GIT_SUBTREE_XML := git-subtree.xml
-GIT_SUBTREE_TXT := git-subtree.txt
+GIT_SUBTREE_TXT := git-subtree.adoc
 GIT_SUBTREE_HTML := git-subtree.html
 GIT_SUBTREE_TEST := ../../git-subtree
 
diff --git a/contrib/subtree/git-subtree.txt b/contrib/subtree/git-subtree.adoc
similarity index 100%
rename from contrib/subtree/git-subtree.txt
rename to contrib/subtree/git-subtree.adoc

-- 
2.49.0.rc0
Patrick Steinhardt· Feb 28, 2025, 08:13 UTC · re: Todd Zullinger · lore

Re: [PATCH 3/3] contrib/subtree: rename .txt to .adoc

On Thu, Feb 27, 2025 at 10:47:06PM -0500, Todd Zullinger wrote:
> The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc
> extension for AsciiDoc files, 2025-01-20).
Same here, we also need the following change on top:
Show changes to contrib/subtree/meson.build +2 −2
diff --git a/contrib/subtree/meson.build b/contrib/subtree/meson.build
index a752a188df1..9c72b236259 100644
--- a/contrib/subtree/meson.build
+++ b/contrib/subtree/meson.build
@@ -32,7 +32,7 @@ if get_option('docs').contains('man')
       '@INPUT@',
     ],
     depends: documentation_deps,
-    input: 'git-subtree.txt',
+    input: 'git-subtree.adoc',
     output: 'git-subtree.xml',
   )
 
@@ -63,7 +63,7 @@ if get_option('docs').contains('html')
       '@INPUT@',
     ],
     depends: documentation_deps,
-    input: 'git-subtree.txt',
+    input: 'git-subtree.adoc',
     output: 'git-subtree.html',
     install: true,
     install_dir: get_option('datadir') / 'doc/git-doc',

Patrick
Todd Zullinger· Feb 28, 2025, 13:50 UTC · re: Patrick Steinhardt · lore

Re: [PATCH 3/3] contrib/subtree: rename .txt to .adoc

Patrick Steinhardt wrote:
Show 28 quoted lines
> On Thu, Feb 27, 2025 at 10:47:06PM -0500, Todd Zullinger wrote:
>> The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc
>> extension for AsciiDoc files, 2025-01-20).
> 
> Same here, we also need the following change on top:
> 
> diff --git a/contrib/subtree/meson.build b/contrib/subtree/meson.build
> index a752a188df1..9c72b236259 100644
> --- a/contrib/subtree/meson.build
> +++ b/contrib/subtree/meson.build
> @@ -32,7 +32,7 @@ if get_option('docs').contains('man')
>        '@INPUT@',
>      ],
>      depends: documentation_deps,
> -    input: 'git-subtree.txt',
> +    input: 'git-subtree.adoc',
>      output: 'git-subtree.xml',
>    )
>  
> @@ -63,7 +63,7 @@ if get_option('docs').contains('html')
>        '@INPUT@',
>      ],
>      depends: documentation_deps,
> -    input: 'git-subtree.txt',
> +    input: 'git-subtree.adoc',
>      output: 'git-subtree.html',
>      install: true,
>      install_dir: get_option('datadir') / 'doc/git-doc',

Thanks. I have not yet looked at the meson build so I didn't remember that should be checked. I still build a full set of packages for rpm-based systems and there were a few remaining items which were not covered by meson in 2.49.0-rc0 (or so I thought). :)

In particular, it was contrib/contacts and contrib/subtree; although the latter is obviously not true and the former won't be for long. I'll definitely have to take a stab at building my local rpm's with meson very soon so I have some better testing there.

-- 
Todd
Patrick Steinhardt· Feb 28, 2025, 14:09 UTC · re: Todd Zullinger · lore

Re: [PATCH 3/3] contrib/subtree: rename .txt to .adoc

On Fri, Feb 28, 2025 at 08:50:25AM -0500, Todd Zullinger wrote:
Show 41 quoted lines
> Patrick Steinhardt wrote:
> > On Thu, Feb 27, 2025 at 10:47:06PM -0500, Todd Zullinger wrote:
> >> The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc
> >> extension for AsciiDoc files, 2025-01-20).
> > 
> > Same here, we also need the following change on top:
> > 
> > diff --git a/contrib/subtree/meson.build b/contrib/subtree/meson.build
> > index a752a188df1..9c72b236259 100644
> > --- a/contrib/subtree/meson.build
> > +++ b/contrib/subtree/meson.build
> > @@ -32,7 +32,7 @@ if get_option('docs').contains('man')
> >        '@INPUT@',
> >      ],
> >      depends: documentation_deps,
> > -    input: 'git-subtree.txt',
> > +    input: 'git-subtree.adoc',
> >      output: 'git-subtree.xml',
> >    )
> >  
> > @@ -63,7 +63,7 @@ if get_option('docs').contains('html')
> >        '@INPUT@',
> >      ],
> >      depends: documentation_deps,
> > -    input: 'git-subtree.txt',
> > +    input: 'git-subtree.adoc',
> >      output: 'git-subtree.html',
> >      install: true,
> >      install_dir: get_option('datadir') / 'doc/git-doc',
> 
> Thanks.  I have not yet looked at the meson build so I
> didn't remember that should be checked.  I still build a
> full set of packages for rpm-based systems and there were a
> few remaining items which were not covered by meson in
> 2.49.0-rc0 (or so I thought). :)
> 
> In particular, it was contrib/contacts and contrib/subtree;
> although the latter is obviously not true and the former
> won't be for long.  I'll definitely have to take a stab at
> building my local rpm's with meson very soon so I have some
> better testing there.
That would be great indeed and very much appreciated!
Patrick
Junio C Hamano· Feb 28, 2025, 18:34 UTC · re: Patrick Steinhardt · lore

Re: [PATCH 3/3] contrib/subtree: rename .txt to .adoc

Patrick Steinhardt <ps@pks.im> writes:
Show 5 quoted lines
>> won't be for long.  I'll definitely have to take a stab at
>> building my local rpm's with meson very soon so I have some
>> better testing there.
>
> That would be great indeed and very much appreciated!
Yup, huge thanks to both of you for working well together.
Junio C Hamano· Feb 28, 2025, 13:45 UTC · re: Todd Zullinger · lore

Re: [PATCH 0/3] doc: txt -> adoc fixes

Todd Zullinger <tmz@pobox.com> writes:
Show 5 quoted lines
> I noticed broken links in the howto-index.html output of v2.49.0-rc0.
> This is due to the recent txt -> adoc renaming.  I chose to replace the
> numerous occurences of "txt" with "adoc" in howto-index.sh for consistency
> within the script.  It could be argued that only the few instances which
> glob '*.txt' should be changed, of course.
Thanks for noticing and sending a fix.
Show 19 quoted lines
> I also renamed the git-*.txt files in contrib/contacts and contrib/subtree
> while I was here.  The only other file in contrib which might warrant that
> treatment is contrib/mw-to-git/git-remote-mediawiki.txt.  I skipped it as
> I am not sure whether it is actively maintained anymore.  If we want to
> rename it to be consistent, that's easy enough.
>
> Todd Zullinger (3):
>   doc: update howto-index.sh for .adoc extensions
>   contrib/contacts: rename .txt to .adoc
>   contrib/subtree: rename .txt to .adoc
>
>  Documentation/howto/howto-index.sh                 | 14 +++++++-------
>  contrib/contacts/Makefile                          |  2 +-
>  .../{git-contacts.txt => git-contacts.adoc}        |  0
>  contrib/subtree/Makefile                           |  2 +-
>  .../subtree/{git-subtree.txt => git-subtree.adoc}  |  0
>  5 files changed, 9 insertions(+), 9 deletions(-)
>  rename contrib/contacts/{git-contacts.txt => git-contacts.adoc} (100%)
>  rename contrib/subtree/{git-subtree.txt => git-subtree.adoc} (100%)
Todd Zullinger· Mar 1, 2025, 15:36 UTC · re: Todd Zullinger · lore

[PATCH v2 0/3] doc: txt -> adoc fixes

This series is now based on ps/meson-contrib-bits.
Changes in v2:
  - build on ps/meson-contrib-bits
  - include changes to contrib/contacts/meson.build
v1: https://lore.kernel.org/git/20250228034713.203461-1-tmz@pobox.com/
CI: https://github.com/tmzullinger/git/actions/runs/13605720163
Todd Zullinger (3):
  doc: update howto-index.sh for .adoc extensions
  contrib/contacts: rename .txt to .adoc
  contrib/subtree: rename .txt to .adoc
 Documentation/howto/howto-index.sh                 | 14 +++++++-------
 contrib/contacts/Makefile                          |  2 +-
 .../{git-contacts.txt => git-contacts.adoc}        |  0
 contrib/contacts/meson.build                       |  4 ++--
 contrib/subtree/Makefile                           |  2 +-
 .../subtree/{git-subtree.txt => git-subtree.adoc}  |  0
 contrib/subtree/meson.build                        |  4 ++--
 7 files changed, 13 insertions(+), 13 deletions(-)
 rename contrib/contacts/{git-contacts.txt => git-contacts.adoc} (100%)
 rename contrib/subtree/{git-subtree.txt => git-subtree.adoc} (100%)
-- 
2.49.0.rc0
Todd Zullinger· Mar 1, 2025, 15:36 UTC · re: Todd Zullinger · lore

[PATCH v2 1/3] doc: update howto-index.sh for .adoc extensions

The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc extension for AsciiDoc files, 2025-01-20). This left broken links in the generated howto-index.html.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/howto/howto-index.sh | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)
Show changes to Documentation/howto/howto-index.sh +7 −7
diff --git a/Documentation/howto/howto-index.sh b/Documentation/howto/howto-index.sh
index eecd123a93..ace49830a8 100755
--- a/Documentation/howto/howto-index.sh
+++ b/Documentation/howto/howto-index.sh
@@ -9,9 +9,9 @@ people describing how they use Git in their workflow.
 
 EOF
 
-for txt
+for adoc
 do
-	title=$(expr "$txt" : '.*/\(.*\)\.txt$')
+	title=$(expr "$adoc" : '.*/\(.*\)\.adoc$')
 	from=$(sed -ne '
 	/^$/q
 	/^From:[ 	]/{
@@ -21,7 +21,7 @@ do
 		s/^/by /
 		p
 	}
-	' "$txt")
+	' "$adoc")
 
 	abstract=$(sed -ne '
 	/^Abstract:[ 	]/{
@@ -39,13 +39,13 @@ do
 		x
 		p
 		q
-	}' "$txt")
+	}' "$adoc")
 
-	if grep 'Content-type: text/asciidoc' >/dev/null $txt
+	if grep 'Content-type: text/asciidoc' >/dev/null $adoc
 	then
-		file=$(expr "$txt" : '\(.*\)\.txt$').html
+		file=$(expr "$adoc" : '\(.*\)\.adoc$').html
 	else
-		file="$txt"
+		file="$adoc"
 	fi
 
 	echo "* link:howto/$(basename "$file")[$title] $from

-- 
2.49.0.rc0
Todd Zullinger· Mar 1, 2025, 15:36 UTC · re: Todd Zullinger · lore

[PATCH v2 2/3] contrib/contacts: rename .txt to .adoc

The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc extension for AsciiDoc files, 2025-01-20).

Do the same for contrib/contacts.
Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 contrib/contacts/Makefile                                | 2 +-
 contrib/contacts/{git-contacts.txt => git-contacts.adoc} | 0
 contrib/contacts/meson.build                             | 4 ++--
 3 files changed, 3 insertions(+), 3 deletions(-)
 rename contrib/contacts/{git-contacts.txt => git-contacts.adoc} (100%)
Show changes to 3 files +3 −3

contrib/contacts/Makefile, contrib/contacts/git-contacts.txt, contrib/contacts/meson.build

diff --git a/contrib/contacts/Makefile b/contrib/contacts/Makefile
index a2990f0dcb..9c4ca4f3bc 100644
--- a/contrib/contacts/Makefile
+++ b/contrib/contacts/Makefile
@@ -34,7 +34,7 @@ GIT_CONTACTS := git-contacts
 
 GIT_CONTACTS_DOC := git-contacts.1
 GIT_CONTACTS_XML := git-contacts.xml
-GIT_CONTACTS_TXT := git-contacts.txt
+GIT_CONTACTS_TXT := git-contacts.adoc
 GIT_CONTACTS_HTML := git-contacts.html
 
 doc: $(GIT_CONTACTS_DOC) $(GIT_CONTACTS_HTML)
diff --git a/contrib/contacts/git-contacts.txt b/contrib/contacts/git-contacts.adoc
similarity index 100%
rename from contrib/contacts/git-contacts.txt
rename to contrib/contacts/git-contacts.adoc
diff --git a/contrib/contacts/meson.build b/contrib/contacts/meson.build
index 6ec92f47c4..73d82dfe52 100644
--- a/contrib/contacts/meson.build
+++ b/contrib/contacts/meson.build
@@ -16,7 +16,7 @@ if get_option('docs').contains('man')
       '@INPUT@',
     ],
     depends: documentation_deps,
-    input: 'git-contacts.txt',
+    input: 'git-contacts.adoc',
     output: 'git-contacts.xml',
   )
 
@@ -47,7 +47,7 @@ if get_option('docs').contains('html')
       '@INPUT@',
     ],
     depends: documentation_deps,
-    input: 'git-contacts.txt',
+    input: 'git-contacts.adoc',
     output: 'git-contacts.html',
     install: true,
     install_dir: get_option('datadir') / 'doc/git-doc',

-- 
2.49.0.rc0
Todd Zullinger· Mar 1, 2025, 15:36 UTC · re: Todd Zullinger · lore

[PATCH v2 3/3] contrib/subtree: rename .txt to .adoc

The .txt extensions were changed to .adoc in 1f010d6bdf (doc: use .adoc extension for AsciiDoc files, 2025-01-20).

Do the same for contrib/subtree.
Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 contrib/subtree/Makefile                              | 2 +-
 contrib/subtree/{git-subtree.txt => git-subtree.adoc} | 0
 contrib/subtree/meson.build                           | 4 ++--
 3 files changed, 3 insertions(+), 3 deletions(-)
 rename contrib/subtree/{git-subtree.txt => git-subtree.adoc} (100%)
Show changes to 3 files +3 −3

contrib/subtree/Makefile, contrib/subtree/git-subtree.txt, contrib/subtree/meson.build

diff --git a/contrib/subtree/Makefile b/contrib/subtree/Makefile
index 8fe0bfd401..c0c9f21cb7 100644
--- a/contrib/subtree/Makefile
+++ b/contrib/subtree/Makefile
@@ -50,7 +50,7 @@ GIT_SUBTREE    := git-subtree
 
 GIT_SUBTREE_DOC := git-subtree.1
 GIT_SUBTREE_XML := git-subtree.xml
-GIT_SUBTREE_TXT := git-subtree.txt
+GIT_SUBTREE_TXT := git-subtree.adoc
 GIT_SUBTREE_HTML := git-subtree.html
 GIT_SUBTREE_TEST := ../../git-subtree
 
diff --git a/contrib/subtree/git-subtree.txt b/contrib/subtree/git-subtree.adoc
similarity index 100%
rename from contrib/subtree/git-subtree.txt
rename to contrib/subtree/git-subtree.adoc
diff --git a/contrib/subtree/meson.build b/contrib/subtree/meson.build
index a752a188df..9c72b23625 100644
--- a/contrib/subtree/meson.build
+++ b/contrib/subtree/meson.build
@@ -32,7 +32,7 @@ if get_option('docs').contains('man')
       '@INPUT@',
     ],
     depends: documentation_deps,
-    input: 'git-subtree.txt',
+    input: 'git-subtree.adoc',
     output: 'git-subtree.xml',
   )
 
@@ -63,7 +63,7 @@ if get_option('docs').contains('html')
       '@INPUT@',
     ],
     depends: documentation_deps,
-    input: 'git-subtree.txt',
+    input: 'git-subtree.adoc',
     output: 'git-subtree.html',
     install: true,
     install_dir: get_option('datadir') / 'doc/git-doc',

-- 
2.49.0.rc0
Junio C Hamano· Mar 1, 2025, 18:02 UTC · re: Todd Zullinger · lore

Re: [PATCH v2 0/3] doc: txt -> adoc fixes

Todd Zullinger <tmz@pobox.com> writes:
Show 24 quoted lines
> This series is now based on ps/meson-contrib-bits.
>
> Changes in v2:
>   - build on ps/meson-contrib-bits
>   - include changes to contrib/contacts/meson.build
>
> v1: https://lore.kernel.org/git/20250228034713.203461-1-tmz@pobox.com/
> CI: https://github.com/tmzullinger/git/actions/runs/13605720163
>
> Todd Zullinger (3):
>   doc: update howto-index.sh for .adoc extensions
>   contrib/contacts: rename .txt to .adoc
>   contrib/subtree: rename .txt to .adoc
>
>  Documentation/howto/howto-index.sh                 | 14 +++++++-------
>  contrib/contacts/Makefile                          |  2 +-
>  .../{git-contacts.txt => git-contacts.adoc}        |  0
>  contrib/contacts/meson.build                       |  4 ++--
>  contrib/subtree/Makefile                           |  2 +-
>  .../subtree/{git-subtree.txt => git-subtree.adoc}  |  0
>  contrib/subtree/meson.build                        |  4 ++--
>  7 files changed, 13 insertions(+), 13 deletions(-)
>  rename contrib/contacts/{git-contacts.txt => git-contacts.adoc} (100%)
>  rename contrib/subtree/{git-subtree.txt => git-subtree.adoc} (100%)
All looking good.  Will queue.
Thanks.
Junio C Hamano· Mar 1, 2025, 18:20 UTC · re: Todd Zullinger · lore

Re: [PATCH v2 0/3] doc: txt -> adoc fixes

Todd Zullinger <tmz@pobox.com> writes:
Show 24 quoted lines
> This series is now based on ps/meson-contrib-bits.
>
> Changes in v2:
>   - build on ps/meson-contrib-bits
>   - include changes to contrib/contacts/meson.build
>
> v1: https://lore.kernel.org/git/20250228034713.203461-1-tmz@pobox.com/
> CI: https://github.com/tmzullinger/git/actions/runs/13605720163
>
> Todd Zullinger (3):
>   doc: update howto-index.sh for .adoc extensions
>   contrib/contacts: rename .txt to .adoc
>   contrib/subtree: rename .txt to .adoc
>
>  Documentation/howto/howto-index.sh                 | 14 +++++++-------
>  contrib/contacts/Makefile                          |  2 +-
>  .../{git-contacts.txt => git-contacts.adoc}        |  0
>  contrib/contacts/meson.build                       |  4 ++--
>  contrib/subtree/Makefile                           |  2 +-
>  .../subtree/{git-subtree.txt => git-subtree.adoc}  |  0
>  contrib/subtree/meson.build                        |  4 ++--
>  7 files changed, 13 insertions(+), 13 deletions(-)
>  rename contrib/contacts/{git-contacts.txt => git-contacts.adoc} (100%)
>  rename contrib/subtree/{git-subtree.txt => git-subtree.adoc} (100%)

There still are references to .txt in Documentation/build-docdep.perl and I wonder if we should also address it?

I know for recent builds Documentation/doc.dep seems to be empty after a build, while the file is full of lines after building older releases like Git 2.48.1.

Junio C Hamano· Mar 1, 2025, 18:25 UTC · re: Junio C Hamano · lore

[PATCH v2 4/3] doc: fix build-docdep.perl

We renamed from .txt to .adoc all the asciidoc source files and necessary includes. We also need to adjust the build-docdep tool to work on files whose suffix is .adoc when computing the documentation dependencies.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/build-docdep.perl | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)
Show changes to diff +12 −12
diff --git c/Documentation/build-docdep.perl w/Documentation/build-docdep.perl
index 315efaa2fa..781da12b2e 100755
--- c/Documentation/build-docdep.perl
+++ w/Documentation/build-docdep.perl
@@ -4,15 +4,15 @@
 my %include = ();
 my %included = ();
 
-for my $text (<*.txt>) {
-    open I, '<', $text || die "cannot read: $text";
+for my $adoc (<*.adoc>) {
+    open I, '<', $adoc || die "cannot read: $adoc";
     while (<I>) {
 	if (/^include::/) {
 	    chomp;
 	    s/^include::\s*//;
 	    s/\[\]//;
 	    s/{build_dir}/${build_dir}/;
-	    $include{$text}{$_} = 1;
+	    $include{$adoc}{$_} = 1;
 	    $included{$_} = 1;
 	}
     }
@@ -23,14 +23,14 @@
 my $changed = 1;
 while ($changed) {
     $changed = 0;
-    while (my ($text, $included) = each %include) {
+    while (my ($adoc, $included) = each %include) {
 	for my $i (keys %$included) {
-	    # $text has include::$i; if $i includes $j
-	    # $text indirectly includes $j.
+	    # $adoc has include::$i; if $i includes $j
+	    # $adoc indirectly includes $j.
 	    if (exists $include{$i}) {
 		for my $j (keys %{$include{$i}}) {
-		    if (!exists $include{$text}{$j}) {
-			$include{$text}{$j} = 1;
+		    if (!exists $include{$adoc}{$j}) {
+			$include{$adoc}{$j} = 1;
 			$included{$j} = 1;
 			$changed = 1;
 		    }
@@ -40,10 +40,10 @@
     }
 }
 
-foreach my $text (sort keys %include) {
-    my $included = $include{$text};
-    if (! exists $included{$text} &&
-	(my $base = $text) =~ s/\.txt$//) {
+foreach my $adoc (sort keys %include) {
+    my $included = $include{$adoc};
+    if (! exists $included{$adoc} &&
+	(my $base = $adoc) =~ s/\.adoc$//) {
 	print "$base.html $base.xml : ", join(" ", sort keys %$included), "\n";
     }
 }
Todd Zullinger· Mar 1, 2025, 19:41 UTC · re: Junio C Hamano · lore

Re: [PATCH v2 4/3] doc: fix build-docdep.perl

Junio C Hamano wrote:
> We renamed from .txt to .adoc all the asciidoc source files and
> necessary includes.  We also need to adjust the build-docdep tool to
> work on files whose suffix is .adoc when computing the documentation
> dependencies.

Good catch. This change looks obviously correct. Testing shows that it generates the same content as in 2.48.1, apart from 2 small changes due to adding config/trailers.adoc in the 2.49.0 cycle.

I took a look though the output of `git grep -F .txt` to see what other low-hanging and/or important fruit there was. It's a decent list, though I don't know that most of it is crucial (any more or less than imperfect documentation ever is).

Here's a "quick" list of what I noted while perusing that. I may try to fix up some of these, but I doubt I'll get to the majority of them anytime soon. Even if I or someone else did, it may not be worth the review time during the RC cycle to try?

There references to .txt in various .gitattributes files. I suspect that Documentation/.gitattributes could just be removed. It contains only `*.txt whitespace`. [It was last changed when it was added in 14f9e128d3 (Define the project whitespace policy, 2008-02-10). :)]

Other references to .txt files appear in the top-level .gitattributes which should likely be updated:

    /Documentation/git-merge.txt conflict-marker-size=32
    /Documentation/gitk.txt conflict-marker-size=32
    /Documentation/user-manual.txt conflict-marker-size=32

These were added in b9b07efdb2 (.gitattributes: add conflict-marker-size for relevant files, 2018-08-28).

The README.md, Documentation/CodingGuidelines, and Documnetation/MyFirstContribution.adoc files all reference various Documentation/*.txt paths. It's probably a little cruel to make first time contributors who are diligent enough to read the docs then stumble over outdated information. :)

Documentation/howto/new-command.adoc references api-builtin.txt, but that was removed long before the adoc renaming, in ec14d4ecb5 (builtin.h: take over documentation from api-builtin.txt, 2017-08-02).

Documentation/technical/partial-clone.adoc references Documentation/rev-list-options.txt..

Makefile references Documentation/technical/racy-git.txt.

And there are a smattering of code comments which direct folks to various Documentation/*.txt files. Those are worth fixing, but likely anyone deep in the weeks of fsck.h will be able to find their way from Documentation/fsck-msgids.txt to Documentation/fsck-msgids.adoc. ;)

Cheers,
-- 
Todd

← back to recent threads