From 28f4c68f9613dde442ce06a7cf59ff1f1278a1e8 Mon Sep 17 00:00:00 2001
From: Ihnatus <ignatus31oct@mail.ru>
Date: Sun, 29 Jun 2025 20:34:26 +0300
Subject: [PATCH] Document [super_specialist_???] section names

This adds a new ruleutil comment.

See FCRM#1410

Signed-off-by: Ihnatus <ignatus31oct@mail.ru>
---
 data/alien/cities.ruleset         | 12 ++++++++++++
 data/civ1/cities.ruleset          | 12 ++++++++++++
 data/civ2/cities.ruleset          | 12 ++++++++++++
 data/civ2civ3/cities.ruleset      | 12 ++++++++++++
 data/classic/cities.ruleset       |  6 ++++++
 data/goldkeep/cities.ruleset      | 12 ++++++++++++
 data/granularity/cities.ruleset   | 12 ++++++++++++
 data/multiplayer/cities.ruleset   | 12 ++++++++++++
 data/ruledit/comments-3.4.txt     |  9 +++++++++
 data/sandbox/cities.ruleset       | 12 ++++++++++++
 data/stub/cities.ruleset          | 12 ++++++++++++
 data/webperimental/cities.ruleset | 12 ++++++++++++
 tools/ruleutil/comments.c         | 10 ++++++++++
 tools/ruleutil/comments.h         |  1 +
 tools/ruleutil/rulesave.c         | 14 ++++++++++++--
 15 files changed, 158 insertions(+), 2 deletions(-)

diff --git a/data/alien/cities.ruleset b/data/alien/cities.ruleset
index 11e8bf4dc4..0e71a51316 100644
--- a/data/alien/cities.ruleset
+++ b/data/alien/cities.ruleset
@@ -88,6 +88,18 @@ helptext = _("\
 Government Merchants produce two gold for the government each turn, \
 four once Specialist Training tech is known.")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/civ1/cities.ruleset b/data/civ1/cities.ruleset
index f295380a84..5e69eec6b6 100644
--- a/data/civ1/cities.ruleset
+++ b/data/civ1/cities.ruleset
@@ -88,6 +88,18 @@ Each tax collector produces two extra gold for your treasury \
 per turn.\
 ")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/civ2/cities.ruleset b/data/civ2/cities.ruleset
index f295380a84..5e69eec6b6 100644
--- a/data/civ2/cities.ruleset
+++ b/data/civ2/cities.ruleset
@@ -88,6 +88,18 @@ Each tax collector produces two extra gold for your treasury \
 per turn.\
 ")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/civ2civ3/cities.ruleset b/data/civ2civ3/cities.ruleset
index 17134129b5..264e5128b1 100644
--- a/data/civ2civ3/cities.ruleset
+++ b/data/civ2civ3/cities.ruleset
@@ -91,6 +91,18 @@ per turn, increasing to three once any player has built \
 A.Smith's Trading Co.\
 ")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/classic/cities.ruleset b/data/classic/cities.ruleset
index fc0fc252c0..7f617e2f98 100644
--- a/data/classic/cities.ruleset
+++ b/data/classic/cities.ruleset
@@ -88,6 +88,12 @@ Each tax collector produces three extra gold for your treasury \
 per turn.\
 ")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/goldkeep/cities.ruleset b/data/goldkeep/cities.ruleset
index cb82cace13..1a7d14d8f9 100644
--- a/data/goldkeep/cities.ruleset
+++ b/data/goldkeep/cities.ruleset
@@ -90,6 +90,18 @@ Each tax collector produces three extra gold for your treasury \
 per turn.\
 ")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/granularity/cities.ruleset b/data/granularity/cities.ruleset
index 55f14bd407..db702f953b 100644
--- a/data/granularity/cities.ruleset
+++ b/data/granularity/cities.ruleset
@@ -63,6 +63,18 @@ reqs            =
       "Tech", "Science", "Player"
     }
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/multiplayer/cities.ruleset b/data/multiplayer/cities.ruleset
index 700270d94d..42f2588f9f 100644
--- a/data/multiplayer/cities.ruleset
+++ b/data/multiplayer/cities.ruleset
@@ -87,6 +87,18 @@ Each tax collector produces three extra gold for your treasury \
 per turn.\
 ")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/ruledit/comments-3.4.txt b/data/ruledit/comments-3.4.txt
index bd4cf93966..e18be707a1 100644
--- a/data/ruledit/comments-3.4.txt
+++ b/data/ruledit/comments-3.4.txt
@@ -1223,6 +1223,15 @@ specialists = "\
 ; */ <-- avoid gettext warnings\n\
 "
 
+superspecialists = "\
+\n\
+; Superspecialists are similar to specialists but they are not counted\n\
+; within citizens. Players and CMA can't manage them.\n\
+; The tag name in super_specialist_* doesn't matter so long as it's unique.\n\
+; [super_specialist_great_artist]\n\
+; (same parameters as for normal specialist follow)\n\
+"
+
 nations = "\
 \n\
 ; See doc/README.nations for information on how to\n\
diff --git a/data/sandbox/cities.ruleset b/data/sandbox/cities.ruleset
index 5815d20c7d..8527c902d3 100644
--- a/data/sandbox/cities.ruleset
+++ b/data/sandbox/cities.ruleset
@@ -91,6 +91,18 @@ per turn, increasing to three once any player has built \
 A.Smith's Trading Co.\
 ")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/stub/cities.ruleset b/data/stub/cities.ruleset
index d7b860be91..d27896ad51 100644
--- a/data/stub/cities.ruleset
+++ b/data/stub/cities.ruleset
@@ -47,6 +47,18 @@ reqs            =
 ; No requirements
     }
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/data/webperimental/cities.ruleset b/data/webperimental/cities.ruleset
index 2656ed476c..a240b7a947 100644
--- a/data/webperimental/cities.ruleset
+++ b/data/webperimental/cities.ruleset
@@ -88,6 +88,18 @@ Each tax collector produces three extra gold for your treasury \
 per turn.\
 ")
 
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in superspecialist_* doesn't matter so long as it's unique.
+; [superspecialist_great_artist]
+; (same parameters as for normal specialist follow)
+
+; Superspecialists are similar to specialists but they are not counted
+; within citizens. Players and CMA can't manage them.
+; The tag name in super_specialist_* doesn't matter so long as it's unique.
+; [super_specialist_great_artist]
+; (same parameters as for normal specialist follow)
+
 [parameters]
 add_to_size_limit  = 8		; cities >= this cannot be added to.
 angry_citizens = TRUE           ; set to FALSE to disable angry citizens
diff --git a/tools/ruleutil/comments.c b/tools/ruleutil/comments.c
index f317391732..648e2a8445 100644
--- a/tools/ruleutil/comments.c
+++ b/tools/ruleutil/comments.c
@@ -56,6 +56,7 @@ static struct {
   char *actions;
   char *enablers;
   char *specialists;
+  char *superspecialists;
   char *nations;
   char *nationgroups;
   char *nationsets;
@@ -181,6 +182,8 @@ bool comments_load(void)
   comment_load(comments_storage.enablers, comment_file, "typedoc.enablers");
   comment_load(comments_storage.specialists,
                comment_file, "typedoc.specialists");
+  comment_load(comments_storage.superspecialists,
+               comment_file, "typedoc.superspecialists");
   comment_load(comments_storage.nations, comment_file, "typedoc.nations");
   comment_load(comments_storage.nationgroups,
                comment_file, "typedoc.nationgroups");
@@ -551,6 +554,13 @@ void comment_specialists(struct section_file *sfile)
   comment_write(sfile, comments_storage.specialists, "Specialists");
 }
 
+/**********************************************************************//**
+  Write superspecialists header.
+**************************************************************************/
+void comment_superspecialists(struct section_file *sfile)
+{
+  comment_write(sfile, comments_storage.superspecialists, "Superspecialists");
+}
 /**********************************************************************//**
   Write nations header.
 **************************************************************************/
diff --git a/tools/ruleutil/comments.h b/tools/ruleutil/comments.h
index e20e8809a8..c87e79ae27 100644
--- a/tools/ruleutil/comments.h
+++ b/tools/ruleutil/comments.h
@@ -51,6 +51,7 @@ void comment_goods(struct section_file *sfile);
 void comment_actions(struct section_file *sfile);
 void comment_enablers(struct section_file *sfile);
 void comment_specialists(struct section_file *sfile);
+void comment_superspecialists(struct section_file *sfile);
 void comment_nationsets(struct section_file *sfile);
 void comment_nationgroups(struct section_file *sfile);
 void comment_nations(struct section_file *sfile);
diff --git a/tools/ruleutil/rulesave.c b/tools/ruleutil/rulesave.c
index 71e0c703bc..3d7545dead 100644
--- a/tools/ruleutil/rulesave.c
+++ b/tools/ruleutil/rulesave.c
@@ -673,6 +673,7 @@ static bool save_cities_ruleset(const char *filename, const char *name)
 {
   struct section_file *sfile = create_ruleset_file(name, "cities");
   int sect_idx;
+  bool supers = FALSE;
 
   if (sfile == nullptr) {
     return FALSE;
@@ -684,10 +685,15 @@ static bool save_cities_ruleset(const char *filename, const char *name)
   specialist_type_iterate(sp) {
     struct specialist *s = specialist_by_number(sp);
     char path[512];
+    bool is_super = is_super_specialist_id(sp);
 
+    if (is_super && !supers) {
+      /* Superspecialists started */
+      comment_superspecialists(sfile);
+      supers = TRUE;
+    }
     fc_snprintf(path, sizeof(path),
-                is_super_specialist_id(sp)
-                ? "super_specialist_%d" : "specialist_%d", sect_idx++);
+                is_super ? "super_specialist_%d" : "specialist_%d", sect_idx++);
 
     save_name_translation(sfile, &(s->name), path);
 
@@ -706,6 +712,10 @@ static bool save_cities_ruleset(const char *filename, const char *name)
     save_strvec(sfile, s->helptext, path, "helptext");
 
   } specialist_type_iterate_end;
+  if (!supers) {
+    /* Just leave it here */
+    comment_superspecialists(sfile);
+  }
 
   if (game.info.celebratesize != GAME_DEFAULT_CELEBRATESIZE) {
     secfile_insert_int(sfile, game.info.celebratesize,
-- 
2.45.2

