From 4780b356dbfb35c3b6cab5be0f4e4cc709e69242 Mon Sep 17 00:00:00 2001
From: Marko Lindqvist <cazfi74@gmail.com>
Date: Sat, 9 Nov 2024 18:28:03 +0200
Subject: [PATCH 77/77] Add documentary comment about action sections

See RM #1093

Signed-off-by: Marko Lindqvist <cazfi74@gmail.com>
---
 data/alien/actions.ruleset         | 19 +++++++++++++++++++
 data/civ1/actions.ruleset          | 19 +++++++++++++++++++
 data/civ2/actions.ruleset          | 19 +++++++++++++++++++
 data/civ2civ3/actions.ruleset      | 19 +++++++++++++++++++
 data/classic/actions.ruleset       | 19 +++++++++++++++++++
 data/goldkeep/actions.ruleset      | 19 +++++++++++++++++++
 data/granularity/actions.ruleset   | 19 +++++++++++++++++++
 data/multiplayer/actions.ruleset   | 19 +++++++++++++++++++
 data/ruledit/comments-3.3.txt      | 26 ++++++++++++++++++--------
 data/sandbox/actions.ruleset       | 19 +++++++++++++++++++
 data/stub/actions.ruleset          | 19 +++++++++++++++++++
 data/webperimental/actions.ruleset | 19 +++++++++++++++++++
 tools/ruleutil/comments.c          | 21 ++++++++++-----------
 tools/ruleutil/comments.h          |  2 +-
 tools/ruleutil/rulesave.c          |  3 +--
 15 files changed, 239 insertions(+), 22 deletions(-)

diff --git a/data/alien/actions.ruleset b/data/alien/actions.ruleset
index b3710a3530..5fb548b029 100644
--- a/data/alien/actions.ruleset
+++ b/data/alien/actions.ruleset
@@ -368,6 +368,25 @@ diplchance_initial_odds = "Sabotage City", "Steal Tech", "Incite City"
 ; requirements. Avoid double entries in the auto help by silencing it.
 quiet_actions = "Transport Disembark 2", "Enter Hut 2", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/civ1/actions.ruleset b/data/civ1/actions.ruleset
index 4bc28437cc..afac2f09cf 100644
--- a/data/civ1/actions.ruleset
+++ b/data/civ1/actions.ruleset
@@ -349,6 +349,25 @@ diplchance_initial_odds = "Sabotage City", "Steal Tech", "Incite City"
 ; double entries in the auto help by silencing it.
 quiet_actions = "Enter Hut 2", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/civ2/actions.ruleset b/data/civ2/actions.ruleset
index d1fa74ccd9..2b4ac8fdb7 100644
--- a/data/civ2/actions.ruleset
+++ b/data/civ2/actions.ruleset
@@ -403,6 +403,25 @@ diplchance_initial_odds = "Sabotage City", "Sabotage City Escape",
 ; Can make the help text less redundant when you document it your self.
 quiet_actions = "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/civ2civ3/actions.ruleset b/data/civ2civ3/actions.ruleset
index 8543214e7d..03c53bd2c0 100644
--- a/data/civ2civ3/actions.ruleset
+++ b/data/civ2civ3/actions.ruleset
@@ -450,6 +450,25 @@ diplchance_initial_odds = "Sabotage City", "Sabotage City Escape",
 quiet_actions = "Transport Disembark 2", "Conquer City Shrink 2", "Enter Hut 2",
                 "Frighten Hut 2", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/classic/actions.ruleset b/data/classic/actions.ruleset
index bae2eaae90..d07d6feb1d 100644
--- a/data/classic/actions.ruleset
+++ b/data/classic/actions.ruleset
@@ -442,6 +442,25 @@ diplchance_initial_odds = "Sabotage City", "Sabotage City Escape",
 quiet_actions = "Transport Disembark 2", "Conquer City Shrink 2", "Enter Hut 2",
                 "Frighten Hut 2", "Conquer Extras 2", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/goldkeep/actions.ruleset b/data/goldkeep/actions.ruleset
index 8a8a48e381..45de4b6b54 100644
--- a/data/goldkeep/actions.ruleset
+++ b/data/goldkeep/actions.ruleset
@@ -442,6 +442,25 @@ diplchance_initial_odds = "Sabotage City", "Sabotage City Escape",
 quiet_actions = "Transport Disembark 2", "Conquer City Shrink 2", "Enter Hut 2",
                 "Frighten Hut 2", "Conquer Extras 2", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/granularity/actions.ruleset b/data/granularity/actions.ruleset
index ff369edf32..2487e6d16a 100644
--- a/data/granularity/actions.ruleset
+++ b/data/granularity/actions.ruleset
@@ -235,6 +235,25 @@ ui_name_conquer_city_shrink = _("%sConquer City%s")
 ; requirements. Avoid double entries in the auto help by silencing it.
 quiet_actions = "Transport Disembark 2", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/multiplayer/actions.ruleset b/data/multiplayer/actions.ruleset
index e72e3565a8..9b153240c1 100644
--- a/data/multiplayer/actions.ruleset
+++ b/data/multiplayer/actions.ruleset
@@ -433,6 +433,25 @@ diplchance_initial_odds = "Sabotage City", "Sabotage City Escape",
 quiet_actions = "Transport Disembark 2", "Conquer City Shrink 2", "Enter Hut 2",
                 "Frighten Hut 2", "Conquer Extras 2", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/ruledit/comments-3.3.txt b/data/ruledit/comments-3.3.txt
index ea5478a6b5..93fca267aa 100644
--- a/data/ruledit/comments-3.3.txt
+++ b/data/ruledit/comments-3.3.txt
@@ -1144,6 +1144,24 @@ goods = "\
 ; */ <-- avoid gettext warnings\n\
 "
 
+actions = "\
+; /* <-- avoid gettext warnings\n\
+;\n\
+; Actions:\n\
+;\n\
+; action               = the action to configure.\n\
+; ui_name              = What each action should be called when showing them to the player.\n\
+;                        The first %s should be before the mnemonic of the action.\n\
+;                        A Freeciv client that supports mnemonics will replace it with\n\
+;                        the in-band signal that marks the following character as a mnemonic\n\
+;                        in its graphical toolkit.\n\
+;                        The second %s marks where extra details should be inserted.\n\
+;\n\
+; README.actions lists the possible actions\n\
+;\n\
+; */ <-- avoid gettext warnings\n\
+"
+
 enablers = "\
 \n\
 ; /* <-- avoid gettext warnings\n\
@@ -1513,14 +1531,6 @@ auto_attack = "\n\
 ;                    they should be tried.\n\
 "
 
-ui_names = "\n\
-; What each action should be called when showing them to the player.\n\
-; The first \%s should be before the mnemonic of the action. A Freeciv client\n\
-; that supports mnemonics will replace it with the in-band signal that marks\n\
-; the following character as a mnemonic in its graphical toolkit.\n\
-; The second \%s marks where extra details should be inserted.\n\
-"
-
 dc_initial_odds = "\n\
 ; Some actions have a action dice roll before the action starts where it can\n\
 ; fail. The initial probability of success is 100% unless the action appears\n\
diff --git a/data/sandbox/actions.ruleset b/data/sandbox/actions.ruleset
index 4f3e185339..033f5c303c 100644
--- a/data/sandbox/actions.ruleset
+++ b/data/sandbox/actions.ruleset
@@ -514,6 +514,25 @@ diplchance_initial_odds = "Sabotage City", "Sabotage City Escape",
 quiet_actions = "Transport Disembark 2", "Conquer City Shrink 2", "Enter Hut 2",
                 "Frighten Hut 2", "Conquer Extras 2", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/stub/actions.ruleset b/data/stub/actions.ruleset
index a5784ba9f5..d7e1fc7f76 100644
--- a/data/stub/actions.ruleset
+++ b/data/stub/actions.ruleset
@@ -175,6 +175,25 @@ found_city_consuming_always = TRUE
 ; Can make the help text less redundant when you document it your self.
 ;quiet_actions = "Targeted Sabotage City", "Targeted Steal Tech", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/data/webperimental/actions.ruleset b/data/webperimental/actions.ruleset
index 7115e0f5fb..4d3ae34a6b 100644
--- a/data/webperimental/actions.ruleset
+++ b/data/webperimental/actions.ruleset
@@ -403,6 +403,25 @@ diplchance_initial_odds = "Steal Gold", "Steal Gold Escape",
 ; Can make the help text less redundant when you document it your self.
 quiet_actions = "Heal Unit", "Unit Move"
 
+; /* <-- avoid gettext warnings
+;
+; Actions:
+;
+; action               = the action to configure.
+; ui_name              = What each action should be called when showing them to the player.
+;                        The first %s should be before the mnemonic of the action.
+;                        A Freeciv client that supports mnemonics will replace it with
+;                        the in-band signal that marks the following character as a mnemonic
+;                        in its graphical toolkit.
+;                        The second %s marks where extra details should be inserted.
+;
+; README.actions lists the possible actions
+;
+; */ <-- avoid gettext warnings
+
+;[action_placeholder]
+
+
 ; /* <-- avoid gettext warnings
 ;
 ; Enablers:
diff --git a/tools/ruleutil/comments.c b/tools/ruleutil/comments.c
index 4508eb1346..e9ec720d5c 100644
--- a/tools/ruleutil/comments.c
+++ b/tools/ruleutil/comments.c
@@ -53,6 +53,7 @@ static struct {
   char *uflags_building;
   char *trade_settings;
   char *goods;
+  char *actions;
   char *enablers;
   char *specialists;
   char *nations;
@@ -85,7 +86,6 @@ static struct {
   char *combat_rules_nuke_pop_loss;
   char *combat_rules_nuke_defender_survival;
   char *auto_attack;
-  char *actions_ui_names;
   char *actions_dc_initial_odds;
   char *actions_quiet_actions;
   char *borders_radius_permanent;
@@ -178,6 +178,7 @@ bool comments_load(void)
   comment_load(comments_storage.trade_settings,
                comment_file, "typedoc.trade_settings");
   comment_load(comments_storage.goods, comment_file, "typedoc.goods");
+  comment_load(comments_storage.actions, comment_file, "typedoc.actions");
   comment_load(comments_storage.enablers, comment_file, "typedoc.enablers");
   comment_load(comments_storage.specialists,
                comment_file, "typedoc.specialists");
@@ -234,8 +235,6 @@ bool comments_load(void)
                "entrydoc.nuke_defender_survival_chance_pct");
   comment_load(comments_storage.auto_attack, comment_file,
                "entrydoc.auto_attack");
-  comment_load(comments_storage.actions_ui_names, comment_file,
-               "entrydoc.ui_names");
   comment_load(comments_storage.actions_dc_initial_odds, comment_file,
                "entrydoc.dc_initial_odds");
   comment_load(comments_storage.actions_quiet_actions, comment_file,
@@ -531,6 +530,14 @@ void comment_goods(struct section_file *sfile)
   comment_write(sfile, comments_storage.goods, "Goods");
 }
 
+/**********************************************************************//**
+  Write actions header.
+**************************************************************************/
+void comment_actions(struct section_file *sfile)
+{
+  comment_write(sfile, comments_storage.actions, "Actions");
+}
+
 /**********************************************************************//**
   Write action enablers header.
 **************************************************************************/
@@ -784,14 +791,6 @@ void comment_auto_attack(struct section_file *sfile)
   comment_entry_write(sfile, comments_storage.auto_attack, "auto_attack");
 }
 
-/**********************************************************************//**
-  Write actions ui_name settings header.
-**************************************************************************/
-void comment_actions_ui_names(struct section_file *sfile)
-{
-  comment_entry_write(sfile, comments_storage.actions_ui_names, "actions");
-}
-
 /**********************************************************************//**
   Write actions diplchance_initial_odds settings header.
 **************************************************************************/
diff --git a/tools/ruleutil/comments.h b/tools/ruleutil/comments.h
index d83e2abfd4..2d61bcdbb8 100644
--- a/tools/ruleutil/comments.h
+++ b/tools/ruleutil/comments.h
@@ -48,6 +48,7 @@ void comment_ueffs(struct section_file *sfile);
 void comment_disasters(struct section_file *sfile);
 void comment_achievements(struct section_file *sfile);
 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_nationsets(struct section_file *sfile);
@@ -88,7 +89,6 @@ void comment_combat_rules_low_fp_nonnat_bombard(struct section_file *sfile);
 void comment_combat_rules_nuke_pop_loss(struct section_file *sfile);
 void comment_combat_rules_nuke_defender_survival(struct section_file *sfile);
 void comment_auto_attack(struct section_file *sfile);
-void comment_actions_ui_names(struct section_file *sfile);
 void comment_actions_dc_initial_odds(struct section_file *sfile);
 void comment_actions_quiet_actions(struct section_file *sfile);
 void comment_borders_radius_permanent(struct section_file *sfile);
diff --git a/tools/ruleutil/rulesave.c b/tools/ruleutil/rulesave.c
index 51d893951a..8952df58d3 100644
--- a/tools/ruleutil/rulesave.c
+++ b/tools/ruleutil/rulesave.c
@@ -1167,8 +1167,6 @@ static bool save_actions_ruleset(const char *filename, const char *name)
                     RS_DEFAULT_STEAL_MAP_REVEALS_CITIES,
                     "actions.steal_maps_reveals_all_cities", nullptr);
 
-  comment_actions_ui_names(sfile);
-
   action_iterate(act_id) {
     struct action *act = action_by_number(act_id);
 
@@ -1195,6 +1193,7 @@ static bool save_actions_ruleset(const char *filename, const char *name)
     return FALSE;
   }
 
+  comment_actions(sfile);
   for (i = 0; i < MAX_NUM_ACTIONS; i++) {
     struct action *paction = action_by_number(i);
 
-- 
2.45.2

