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

Commit Message

Junio C Hamano March 1, 2025, 6:25 p.m. UTC

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 <[e-mail]>
---
 Documentation/build-docdep.perl | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

Comments

Todd Zullinger March 1, 2025, 7:41 p.m. UTC | #1

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,

Patch

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