From 12b6c17575a4b24539b7d17625232fff899c90cf Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
Date: Tue, 30 Apr 2024 22:47:02 -0400
Subject: [PATCH] wikiheaders: Generate wiki pages for defines under a typedef.

These are just there to handle cases where a user stumbles upon a symbol
and punches it into the wiki, so they don't get a 404 for it, but rather
a pointer to where that symbol is relevant.

These pages are generated in the wiki if they don't exist, and are never
overwritten, in case text has been added to them. They are also not bridged
back to the headers or added to the set of manpages.
---
 build-scripts/wikiheaders.pl | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index 737a83547f748..6f66873c69ff4 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -541,6 +541,8 @@ sub usage {
 my %wikisyms = ();  # contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikisyms{"SDL_OpenAudio"}{"Remarks"}.
 my %wikisectionorder = ();   # contains references to array, each array item being a key to a wikipage section in the correct order, like $wikisectionorder{"SDL_OpenAudio"}[2] == 'Remarks'
 
+my %referenceonly = ();  # $referenceonly{"Y"} -> symbol name that this symbol is bound to. This makes wiki pages that say "See X" where "X" is a typedef and "Y" is a define attached to it. These pages are generated in the wiki only and do not bridge to the headers or manpages.
+
 sub print_undocumented_section {
     my $fh = shift;
     my $typestr = shift;
@@ -870,7 +872,11 @@ sub print_undocumented_section {
 
                 if (/\A\s*\Z/) {
                     $blank_lines++;
-                } elsif (/\A\s*\#(define|if|else|elif|endif)(\s+|\Z)/) {
+                } elsif (/\A\s*\#\s*(define|if|else|elif|endif)(\s+|\Z)/) {
+                    if (/\A\s*\#\s*define\s+([a-zA-Z0-9_]*)/) {
+                        $referenceonly{$1} = $sym;
+                    }
+                    # update strings now that we know everything pending is to be applied to this declaration. Add pending blank lines and the new text.
                     if ($blank_lines > 0) {
                         while ($blank_lines > 0) {
                             $additional_decl .= "\n";
@@ -1726,6 +1732,26 @@ sub print_undocumented_section {
         rename($path, "$wikipath/$_.${wikitype}") or die("Can't rename '$path' to '$wikipath/$_.${wikitype}': $!\n");
     }
 
+    # Write out simple redirector pages if they don't already exist.
+    foreach (keys %referenceonly) {
+        my $sym = $_;
+        my $refersto = $referenceonly{$sym};
+        my $path = "$wikipath/$sym.md";  # we only do Markdown for these.
+        next if (-f $path);  # don't overwrite if it already exists. Delete the file if you need a rebuild!
+        open(FH, '>', $path) or die("Can't open '$path': $!\n");
+
+        if (defined $wikipreamble) {
+            my $wikified_preamble = wikify('md', $wikipreamble);
+            print FH "###### $wikified_preamble\n";
+        }
+
+        print FH "# $sym\n\nPlease refer to [$refersto]($refersto) for details.\n\n";
+        #print FH "----\n";
+        #print FH "[CategoryAPI](CategoryAPI)\n\n";
+
+        close(FH);
+    }
+
     if (defined $readmepath) {
         if ( -d $readmepath ) {
             mkdir($wikireadmepath);  # just in case