build-scripts/wikiheaders.pl: Allow a wiki preamble.

This is so we can have everything in SDL_net (etc) start with a
"This is not part of the core SDL API" message.

build-scripts/wikiheaders.pl

@@ -25,6 +25,7 @@ my $wikipath = undef;
 my $warn_about_missing = 0;
 my $copy_direction = 0;
 my $optionsfname = undef;
+my $wikipreamble = undef;
 
 foreach (@ARGV) {
     $warn_about_missing = 1, next if $_ eq '--warn-about-missing';
@@ -75,6 +76,7 @@ if (defined $optionsfname) {
             $projecturl = $val, next if $key eq 'projecturl';
             $wikiurl = $val, next if $key eq 'wikiurl';
             $bugreporturl = $val, next if $key eq 'bugreporturl';
+            $wikipreamble = $val, next if $key eq 'wikipreamble';
         }
     }
     close(OPTIONS);
@@ -604,6 +606,8 @@ while (readdir(DH)) {
     my %sections = ();
     $sections{$current_section} = '';
 
+    my $firstline = 1;
+
     while (<FH>) {
         chomp;
         my $orig = $_;
@@ -611,18 +615,24 @@ while (readdir(DH)) {
         s/\s*\Z//;
 
         if ($type eq 'mediawiki') {
-            if (/\A\= (.*?) \=\Z/) {
+            if (defined($wikipreamble) && $firstline && /\A\=\=\=\=\=\= (.*?) \=\=\=\=\=\=\Z/ && ($1 eq $wikipreamble)) {
+                $firstline = 0;  # skip this.
+                next;
+            } elsif (/\A\= (.*?) \=\Z/) {
+                $firstline = 0;
                 $current_section = ($1 eq $fn) ? '[Brief]' : $1;
                 die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section};
                 push @section_order, $current_section;
                 $sections{$current_section} = '';
             } elsif (/\A\=\= (.*?) \=\=\Z/) {
+                $firstline = 0;
                 $current_section = ($1 eq $fn) ? '[Brief]' : $1;
                 die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section};
                 push @section_order, $current_section;
                 $sections{$current_section} = '';
                 next;
             } elsif (/\A\-\-\-\-\Z/) {
+                $firstline = 0;
                 $current_section = '[footer]';
                 die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section};
                 push @section_order, $current_section;
@@ -630,13 +640,18 @@ while (readdir(DH)) {
                 next;
             }
         } elsif ($type eq 'md') {
-            if (/\A\#+ (.*?)\Z/) {
+            if (defined($wikipreamble) && $firstline && /\A\#\#\#\#\#\# (.*?)\Z/ && ($1 eq $wikipreamble)) {
+                $firstline = 0;  # skip this.
+                next;
+            } elsif (/\A\#+ (.*?)\Z/) {
+                $firstline = 0;
                 $current_section = ($1 eq $fn) ? '[Brief]' : $1;
                 die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section};
                 push @section_order, $current_section;
                 $sections{$current_section} = '';
                 next;
             } elsif (/\A\-\-\-\-\Z/) {
+                $firstline = 0;
                 $current_section = '[footer]';
                 die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section};
                 push @section_order, $current_section;
@@ -647,7 +662,12 @@ while (readdir(DH)) {
             die("Unexpected wiki file type. Fixme!\n");
         }
 
-        $sections{$current_section} .= "$orig\n";
+        if ($firstline) {
+            $firstline = ($_ ne '');
+        }
+        if (!$firstline) {
+            $sections{$current_section} .= "$orig\n";
+        }
     }
     close(FH);
 
@@ -1108,6 +1128,14 @@ if ($copy_direction == 1) {  # --copy-to-headers
         } else { die("Unexpected wikitype '$wikitype'\n"); }
         $$sectionsref{'[footer]'} = $footer;
 
+        if (defined $wikipreamble) {
+            if ($wikitype eq 'mediawiki') {
+                print FH "====== $wikipreamble ======\n";
+            } elsif ($wikitype eq 'md') {
+                print FH "###### $wikipreamble\n";
+            } else { die("Unexpected wikitype '$wikitype'\n"); }
+        }
+
         my $prevsectstr = '';
         my @ordered_sections = (@standard_wiki_sections, defined $wikisectionorderref ? @$wikisectionorderref : ());  # this copies the arrays into one.
         foreach (@ordered_sections) {