ghwikipp: build_categories.php: Allow generation of custom sublists of categories.

From 4ccb931a23bc78ee7c4638e3f24c1ddad1e72e6e Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 14 May 2024 10:30:02 -0400
Subject: [PATCH] build_categories.php: Allow generation of custom sublists of
 categories.

---
 build_categories.php | 75 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 67 insertions(+), 8 deletions(-)

diff --git a/build_categories.php b/build_categories.php
index 2c6c9c4..47efe6f 100755
--- a/build_categories.php
+++ b/build_categories.php
@@ -13,6 +13,8 @@
     'mediawiki' => 'mediawiki'
 ];
 
+$editwarning = '<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->';
+
 $escrawdata = escapeshellarg($raw_data);
 
 putenv("GIT_SSH_COMMAND=ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -q -i $ssh_key_fname");
@@ -103,10 +105,44 @@ function build_category_lists($srcdir)
     closedir($dirp);
 }
 
-function write_category_list($fp, $pages, $ismediawiki)
+function write_category_list($fp, $cats, $singletopic, $ismediawiki)
 {
+    global $editwarning, $categories;
+
+    fputs($fp, "$editwarning\n");
+
+    $pages = NULL;
+
+    if ($singletopic) {
+        fputs($fp, "<!-- BEGIN CATEGORY LIST -->\n");
+        $pages = $categories[$cats];
+    } else {
+        fputs($fp, "<!-- BEGIN CATEGORY LIST: $cats -->\n");
+        $pages = array();
+        $splitcats = explode(',', $cats);
+        if ((count($splitcats) > 0) && isset($categories[trim($splitcats[0])])) {
+            $include_this = true;
+            foreach ($categories[trim($splitcats[0])] as $page => $unused) {
+                $include_this = true;
+                $page = trim($page);
+                foreach ($splitcats as $cat) {
+                    $cat = trim($cat);
+                    if (!isset($categories[$cat][$page])) {
+                        $include_this = false;
+                        break;
+                    }
+                }
+
+                if ($include_this) {
+                    $pages[$page] = true;
+                }
+            }
+        }
+    }
+
     ksort($pages, SORT_STRING|SORT_FLAG_CASE);
-    fputs($fp, "<!-- BEGIN CATEGORY LIST -->\n");
+
+    $at_least_one = false;
     //$last_letter = '';
     foreach ($pages as $p => $unused) {
         // this isn't super-useful when everything starts with "SDL_"  :)
@@ -122,7 +158,17 @@ function write_category_list($fp, $pages, $ismediawiki)
         } else {
             fputs($fp, "- [$p]($p)\n");
         }
+        $at_least_one = true;
     }
+
+    if (!$at_least_one) {
+        if ($ismediawiki) {
+            fputs($fp, "* (none.)\n");
+        } else {
+            fputs($fp, "- (none.)\n");
+        }
+    }
+
     fputs($fp, "<!-- END CATEGORY LIST -->\n");
 }
 
@@ -154,6 +200,7 @@ function find_subdirs($base, $dname, &$output)
 function handle_subdir($dname)
 {
     global $categories;
+    global $editwarning;
 
     $categories = array();
     build_category_lists($dname);
@@ -169,7 +216,8 @@ function handle_subdir($dname)
             $ismediawiki = false;
             $path = "$dname/$cat.md";
             if (!file_exists($path)) {
-                file_put_contents($path, "# $cat\n\n<!-- BEGIN CATEGORY LIST -->\n<!-- END CATEGORY LIST -->\n\n");
+                file_put_contents($path, "# $cat\n\n$editwarning\n<!-- BEGIN CATEGORY LIST -->\n<!-- END CATEGORY LIST -->\n\n");
+                //file_put_contents($path, "# $cat\n\n## Functions\n\n<!-- BEGIN CATEGORY LIST: $cat, CategoryAPIFunction -->\n<!-- END CATEGORY LIST -->\n\n## Datatypes\n\n<!-- BEGIN CATEGORY LIST: $cat, CategoryAPIDatatype -->\n<!-- END CATEGORY LIST -->\n\n## Structs\n\n<!-- BEGIN CATEGORY LIST: $cat, CategoryAPIStruct -->\n<!-- END CATEGORY LIST -->\n\n## Enums\n\n<!-- BEGIN CATEGORY LIST: $cat, CategoryAPIEnum -->\n<!-- END CATEGORY LIST -->\n\n## Macros\n\n<!-- BEGIN CATEGORY LIST: $cat, CategoryAPIMacro -->\n<!-- END CATEGORY LIST -->\n\n");
             }
         }
 
@@ -193,15 +241,18 @@ function handle_subdir($dname)
         $wrote_list = false;
         while (($line = fgets($in)) !== false) {
             //print("LINE: [" . trim($line) . "]\n");
-            if (trim($line) == '----') {  // the footer? Just stuff the list before it, oh well.
+            $trimmed = trim($line);
+            if ($trimmed == $editwarning) {
+                // skip these lines, we'll write them out when we output the actual list.
+            } else if ($trimmed == '----') {  // the footer? Just stuff the list before it, oh well.
                 if (!$wrote_list) {
-                    write_category_list($out, $pages, $ismediawiki);
+                    write_category_list($out, $cat, true, $ismediawiki);
                     $wrote_list = true;
                 }
                 fputs($out, "----\n");
-            } else if (trim($line) == '<!-- BEGIN CATEGORY LIST -->') {
+            } else if ($trimmed == '<!-- BEGIN CATEGORY LIST -->') {  // doesn't list a specific category, do the one the page is named for.
                 if (!$wrote_list) {
-                    write_category_list($out, $pages, $ismediawiki);
+                    write_category_list($out, $cat, true, $ismediawiki);
                     $wrote_list = true;
                 }
                 while (($line = fgets($in)) !== false) {
@@ -209,6 +260,14 @@ function handle_subdir($dname)
                         break;
                     }
                 }
+            } else if (preg_match('/^\<\!\-\- BEGIN CATEGORY LIST: (.*?) \-\-\>$/', $trimmed, $cats) === 1) {  // lists a specific set of subcategories
+                write_category_list($out, $cats[1], false, $ismediawiki);
+                $wrote_list = true;  // if this is here, they probably don't want a global list.
+                while (($line = fgets($in)) !== false) {
+                    if (trim($line) == '<!-- END CATEGORY LIST -->') {
+                        break;
+                    }
+                }
             } else {
                 fputs($out, $line);
             }
@@ -217,7 +276,7 @@ function handle_subdir($dname)
         fclose($in);
 
         if (!$wrote_list) {
-            write_category_list($out, $pages, $ismediawiki);
+            write_category_list($out, $cat, true, $ismediawiki);
         }
 
         fclose($out);