SDL: wikiheaders: Bridge README files in the docs directory to wiki. (25066)

From 2506676f34dc9d3e64ab7bbd9c947b8c13364913 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 28 Feb 2023 11:37:46 -0500
Subject: [PATCH] wikiheaders: Bridge README files in the docs directory to
 wiki.

Fixes #6026.
---
 .wikiheaders-options         |  1 +
 build-scripts/wikiheaders.pl | 52 ++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/.wikiheaders-options b/.wikiheaders-options
index 1747ebe0e53f..c02b648e9ccd 100644
--- a/.wikiheaders-options
+++ b/.wikiheaders-options
@@ -2,6 +2,7 @@ projectfullname = SDL
 projectshortname = SDL
 incsubdir = include/SDL3
 wikisubdir =
+readmesubdir = docs
 apiprefixregex = (SDL_|SDLK_|KMOD_|AUDIO_)
 mainincludefname = SDL.h
 versionfname = include/SDL3/SDL_version.h
diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index 52885471416f..29d62b0789f0 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -3,6 +3,7 @@
 use warnings;
 use strict;
 use Text::Wrap;
+use File::Copy;
 
 $Text::Wrap::huge = 'overflow';
 
@@ -10,6 +11,7 @@
 my $projectshortname = 'SDL';
 my $wikisubdir = '';
 my $incsubdir = 'include';
+my $readmesubdir = undef;
 my $apiprefixregex = undef;
 my $versionfname = 'include/SDL_version.h';
 my $versionmajorregex = '\A\#define\s+SDL_MAJOR_VERSION\s+(\d+)\Z';
@@ -22,6 +24,7 @@
 my $bugreporturl = 'https://github.com/libsdl-org/sdlwiki/issues/new';
 my $srcpath = undef;
 my $wikipath = undef;
+my $wikireadmesubdir = 'README';
 my $warn_about_missing = 0;
 my $copy_direction = 0;
 my $optionsfname = undef;
@@ -71,6 +74,7 @@
             $projectshortname = $val, next if $key eq 'projectshortname';
             $wikisubdir = $val, next if $key eq 'wikisubdir';
             $incsubdir = $val, next if $key eq 'incsubdir';
+            $readmesubdir = $val, next if $key eq 'readmesubdir';
             $versionmajorregex = $val, next if $key eq 'versionmajorregex';
             $versionminorregex = $val, next if $key eq 'versionminorregex';
             $versionpatchregex = $val, next if $key eq 'versionpatchregex';
@@ -493,6 +497,12 @@ sub usage {
 my $incpath = "$srcpath";
 $incpath .= "/$incsubdir" if $incsubdir ne '';
 
+my $wikireadmepath = "$wikipath/$wikireadmesubdir";
+my $readmepath = undef;
+if (defined $readmesubdir) {
+    $readmepath = "$srcpath/$readmesubdir";
+}
+
 opendir(DH, $incpath) or die("Can't opendir '$incpath': $!\n");
 while (readdir(DH)) {
     my $dent = $_;
@@ -1004,6 +1014,19 @@ sub usage {
         rename($path, "$incpath/$header") or die("Can't rename '$path' to '$incpath/$header': $!\n");
     }
 
+    if (defined $readmepath) {
+        if ( -d $wikireadmepath ) {
+            mkdir($readmepath);  # just in case
+            opendir(DH, $wikireadmepath) or die("Can't opendir '$wikireadmepath': $!\n");
+            while (readdir(DH)) {
+                my $dent = $_;
+                if ($dent =~ /\A(.*?)\.md\Z/) {  # we only bridge Markdown files here.
+                    copy("$wikireadmepath/$dent", "$readmepath/README-$dent") or die("failed to copy '$wikireadmepath/$dent' to '$readmepath/README-$dent': $!\n");
+                }
+            }
+            closedir(DH);
+        }
+    }
 } elsif ($copy_direction == -1) { # --copy-to-wiki
 
     if (defined $changeformat) {
@@ -1333,6 +1356,35 @@ sub usage {
         rename($path, "$wikipath/$_.${wikitype}") or die("Can't rename '$path' to '$wikipath/$_.${wikitype}': $!\n");
     }
 
+    if (defined $readmepath) {
+        if ( -d $readmepath ) {
+            mkdir($wikireadmepath);  # just in case
+            opendir(DH, $readmepath) or die("Can't opendir '$readmepath': $!\n");
+            while (readdir(DH)) {
+                my $dent = $_;
+                if ($dent =~ /\AREADME\-(.*?\.md)\Z/) {  # we only bridge Markdown files here.
+                    my $wikifname = $1;
+                    copy("$readmepath/$dent", "$wikireadmepath/$wikifname") or die("failed to copy '$readmepath/$dent' to '$wikireadmepath/$wikifname': $!\n");
+                }
+            }
+            closedir(DH);
+
+            open(FH, '>', "$wikireadmepath/FrontPage.md") or die("Can't open '$wikireadmepath/FrontPage.md': $!\n");
+            print FH "# All READMEs available here\n\n";
+
+            opendir(DH, $wikireadmepath) or die("Can't opendir '$wikireadmepath': $!\n");
+            while (readdir(DH)) {
+                my $dent = $_;
+                if ($dent =~ /\A(.*?)\.(mediawiki|md)\Z/) {
+                    my $wikiname = $1;
+                    print FH "- [$wikiname]($wikiname)\n";
+                }
+            }
+            closedir(DH);
+            close(FH);
+        }
+    }
+
 } elsif ($copy_direction == -2) { # --copy-to-manpages
     # This only takes from the wiki data, since it has sections we omit from the headers, like code examples.