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

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

[Todd Zullinger]

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

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

[Todd Zullinger]

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

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

[Junio C Hamano]

Todd Zullinger <tmz@pobox.com> writes:

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

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

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

[Todd Zullinger]

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%)

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

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

[Patrick Steinhardt]

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',

Patrick

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

[Todd Zullinger]

Patrick Steinhardt wrote:
> 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

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

[Junio C Hamano]

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.

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

[Todd Zullinger]

Junio C Hamano wrote:
> 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. :/

> 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

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

[Todd Zullinger]

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%)

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

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

[Patrick Steinhardt]

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',

Patrick

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

[Todd Zullinger]

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.

-- 
Todd

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

[Patrick Steinhardt]

On Fri, Feb 28, 2025 at 08:50:25AM -0500, Todd Zullinger wrote:
> 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

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

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

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

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

[Junio C Hamano]

Todd Zullinger <tmz@pobox.com> writes:

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

> 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%)

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

[Todd Zullinger]

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

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

[Todd Zullinger]

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

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

[Todd Zullinger]

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%)

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

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

[Todd Zullinger]

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%)

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

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

[Junio C Hamano]

Todd Zullinger <tmz@pobox.com> writes:

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

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

[Junio C Hamano]

Todd Zullinger <tmz@pobox.com> writes:

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

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

[Junio C Hamano]

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(-)

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";
     }
 }

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

[Todd Zullinger]

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