From 635f5e38eb4ddcfb3c999e8f196b26e842b2a6c4 Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 16:33:24 +0200 Subject: [PATCH 01/10] Add param table to dfhack.translation.generateName --- docs/dev/Lua API.rst | 58 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 6ec394112f..7ac1090e6a 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -1060,7 +1060,63 @@ Translation module * ``dfhack.translation.generateName(name,language,type,major_selector,minor_selector)`` - Dynamically generate a name using the same logic the game itself uses. + Dynamically generate a random name using the same logic the game itself uses. + + **Parameters:** + + .. list-table:: + :widths: 15 30 10 + :header-rows: 1 + + * - Name + - Explanation + - Data Type + * - :code:`name` + - | :code:`name` property of the object that will have its name generated. + | + | Example values: + | :code:`df.global.world.entities.all[0].name` + | :code:`df.unit.find(79).name` + | :code:`dfhack.gui.getSelectedUnit().name` + | :code:`df.language_name::new()` + - :code:`df.language_name` + * - :code:`language` + - | Integer index of the language used for generating the name within :code:`df.language_translation`. + | + | Example values: + | :code:`df.global.world.entities.all[0].name.language` + | :code:`df.unit.find(79).name.language` + | :code:`dfhack.gui.getSelectedUnit().name.language` + | :code:`0` + - :code:`int` + * - :code:`type` + - | Integer value of the name type. This ensures that the generated name will be appropriate for the given category of object. For allowed values see :code:`df.language_name_type` enum. + | + | Example values: + | :code:`df.global.world.entities.all[100].name.type` + | :code:`df.unit.find(79).name.type` + | :code:`dfhack.gui.getSelectedUnit().name.type` + | :code:`df.language_name_type.Figure` + | :code:`13` + - :code:`df.language_name_type` + * - :code:`major_selector` + - | Section of the loaded game raws containing words used for generating the name. + | + | Example value for sites belonging to civ with id 100: + | :code:`df.historical_entity.find(100).entity_raw.symbols.symbols_major[df.entity_name_type.SITE]` + | + | Example value for units: + | :code:`df.global.world.raws.language.word_table[0][df.language_name_category.Unit]` + - :code:`df.language_word_table` + * - :code:`minor_selector` + - | Section of the loaded game raws containing words used for generating the name. + | + | Example value for sites belonging to civ with id 100: + | :code:`df.historical_entity.find(100).entity_raw.symbols.symbols_minor[df.entity_name_type.SITE]` + | + | Example value for units: + | :code:`df.global.world.raws.language.word_table[1][df.language_name_category.Unit]` + - :code:`df.language_word_table` Gui module ---------- From 3e16d7680ca7ff92471e7dfe84f1a52161fb0479 Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 16:33:53 +0200 Subject: [PATCH 02/10] Switch from :code:`` to ```` syntax --- docs/dev/Lua API.rst | 60 ++++++++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 7ac1090e6a..63631a126d 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -1071,52 +1071,52 @@ Translation module * - Name - Explanation - Data Type - * - :code:`name` - - | :code:`name` property of the object that will have its name generated. + * - ``name`` + - | ``name`` property of the object that will have its name generated. | | Example values: - | :code:`df.global.world.entities.all[0].name` - | :code:`df.unit.find(79).name` - | :code:`dfhack.gui.getSelectedUnit().name` - | :code:`df.language_name::new()` - - :code:`df.language_name` - * - :code:`language` - - | Integer index of the language used for generating the name within :code:`df.language_translation`. + | ``df.global.world.entities.all[0].name`` + | ``df.unit.find(79).name`` + | ``dfhack.gui.getSelectedUnit().name`` + | ``df.language_name::new()`` + - ``df.language_name`` + * - ``language`` + - | Integer index of the language used for generating the name within ``df.language_translation``. | | Example values: - | :code:`df.global.world.entities.all[0].name.language` - | :code:`df.unit.find(79).name.language` - | :code:`dfhack.gui.getSelectedUnit().name.language` - | :code:`0` - - :code:`int` - * - :code:`type` - - | Integer value of the name type. This ensures that the generated name will be appropriate for the given category of object. For allowed values see :code:`df.language_name_type` enum. + | ``df.global.world.entities.all[0].name.language`` + | ``df.unit.find(79).name.language`` + | ``dfhack.gui.getSelectedUnit().name.language`` + | ``0`` + - ``int`` + * - ``type`` + - | Integer value of the name type. This ensures that the generated name will be appropriate for the given category of object. For allowed values see ``df.language_name_type`` enum. | | Example values: - | :code:`df.global.world.entities.all[100].name.type` - | :code:`df.unit.find(79).name.type` - | :code:`dfhack.gui.getSelectedUnit().name.type` - | :code:`df.language_name_type.Figure` - | :code:`13` - - :code:`df.language_name_type` - * - :code:`major_selector` + | ``df.global.world.entities.all[100].name.type`` + | ``df.unit.find(79).name.type`` + | ``dfhack.gui.getSelectedUnit().name.type`` + | ``df.language_name_type.Figure`` + | ``13`` + - ``df.language_name_type`` + * - ``major_selector`` - | Section of the loaded game raws containing words used for generating the name. | | Example value for sites belonging to civ with id 100: - | :code:`df.historical_entity.find(100).entity_raw.symbols.symbols_major[df.entity_name_type.SITE]` + | ``df.historical_entity.find(100).entity_raw.symbols.symbols_major[df.entity_name_type.SITE]`` | | Example value for units: - | :code:`df.global.world.raws.language.word_table[0][df.language_name_category.Unit]` - - :code:`df.language_word_table` - * - :code:`minor_selector` + | ``df.global.world.raws.language.word_table[0][df.language_name_category.Unit]`` + - ``df.language_word_table`` + * - ``minor_selector`` - | Section of the loaded game raws containing words used for generating the name. | | Example value for sites belonging to civ with id 100: - | :code:`df.historical_entity.find(100).entity_raw.symbols.symbols_minor[df.entity_name_type.SITE]` + | ``df.historical_entity.find(100).entity_raw.symbols.symbols_minor[df.entity_name_type.SITE]`` | | Example value for units: - | :code:`df.global.world.raws.language.word_table[1][df.language_name_category.Unit]` - - :code:`df.language_word_table` + | ``df.global.world.raws.language.word_table[1][df.language_name_category.Unit]`` + - ``df.language_word_table`` Gui module ---------- From 89a2cbced7d4893936212d03ab78fcc1133f9bb0 Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 16:33:58 +0200 Subject: [PATCH 03/10] Remove list table widths definition --- docs/dev/Lua API.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 63631a126d..491f0d1750 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -1065,7 +1065,6 @@ Translation module **Parameters:** .. list-table:: - :widths: 15 30 10 :header-rows: 1 * - Name @@ -1087,7 +1086,7 @@ Translation module | ``df.global.world.entities.all[0].name.language`` | ``df.unit.find(79).name.language`` | ``dfhack.gui.getSelectedUnit().name.language`` - | ``0`` + | ``0`` - ``int`` * - ``type`` - | Integer value of the name type. This ensures that the generated name will be appropriate for the given category of object. For allowed values see ``df.language_name_type`` enum. From d211438ab87dc3635cbf2aa33968617f77adfebd Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 16:40:29 +0200 Subject: [PATCH 04/10] Remove trailing whitespace --- docs/dev/Lua API.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 491f0d1750..3c34cb8b11 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -1063,7 +1063,7 @@ Translation module Dynamically generate a random name using the same logic the game itself uses. **Parameters:** - + .. list-table:: :header-rows: 1 @@ -1071,16 +1071,16 @@ Translation module - Explanation - Data Type * - ``name`` - - | ``name`` property of the object that will have its name generated. + - | ``name`` property of the object that will have its name generated. | - | Example values: + | Example values: | ``df.global.world.entities.all[0].name`` | ``df.unit.find(79).name`` | ``dfhack.gui.getSelectedUnit().name`` | ``df.language_name::new()`` - ``df.language_name`` * - ``language`` - - | Integer index of the language used for generating the name within ``df.language_translation``. + - | Integer index of the language used for generating the name within ``df.language_translation``. | | Example values: | ``df.global.world.entities.all[0].name.language`` @@ -1089,7 +1089,7 @@ Translation module | ``0`` - ``int`` * - ``type`` - - | Integer value of the name type. This ensures that the generated name will be appropriate for the given category of object. For allowed values see ``df.language_name_type`` enum. + - | Integer value of the name type. This ensures that the generated name will be appropriate for the given category of object. For allowed values see ``df.language_name_type`` enum. | | Example values: | ``df.global.world.entities.all[100].name.type`` @@ -1100,11 +1100,11 @@ Translation module - ``df.language_name_type`` * - ``major_selector`` - | Section of the loaded game raws containing words used for generating the name. - | + | | Example value for sites belonging to civ with id 100: | ``df.historical_entity.find(100).entity_raw.symbols.symbols_major[df.entity_name_type.SITE]`` - | - | Example value for units: + | + | Example value for units: | ``df.global.world.raws.language.word_table[0][df.language_name_category.Unit]`` - ``df.language_word_table`` * - ``minor_selector`` @@ -1113,7 +1113,7 @@ Translation module | Example value for sites belonging to civ with id 100: | ``df.historical_entity.find(100).entity_raw.symbols.symbols_minor[df.entity_name_type.SITE]`` | - | Example value for units: + | Example value for units: | ``df.global.world.raws.language.word_table[1][df.language_name_category.Unit]`` - ``df.language_word_table`` From 6b3fd87642775e5fc85093da6d555f7935371ddb Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 16:48:43 +0200 Subject: [PATCH 05/10] Remove whitespace --- docs/dev/Lua API.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 3c34cb8b11..93bbe20dfe 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -1091,7 +1091,7 @@ Translation module * - ``type`` - | Integer value of the name type. This ensures that the generated name will be appropriate for the given category of object. For allowed values see ``df.language_name_type`` enum. | - | Example values: + | Example values: | ``df.global.world.entities.all[100].name.type`` | ``df.unit.find(79).name.type`` | ``dfhack.gui.getSelectedUnit().name.type`` From f0ca4dba6ca60095545f66b3c61c265f2b6dde19 Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 16:53:33 +0200 Subject: [PATCH 06/10] Add entry in changelog --- docs/changelog.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/changelog.txt b/docs/changelog.txt index 7d51a61dad..f4ca1a60c0 100644 --- a/docs/changelog.txt +++ b/docs/changelog.txt @@ -63,6 +63,7 @@ Template for new versions: ## Misc Improvements ## Documentation +- ``dfhack.translation.generateName``: added a table containing explanations and data types for each of the parameters ## API From 6a7ac2c2b1dc11a587d1ad7b880d6e9e59fbb1a3 Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 20:03:25 +0200 Subject: [PATCH 07/10] Fix table width --- docs/dev/Lua API.rst | 1 + docs/styles/dfhack.css | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 93bbe20dfe..cc89e3f101 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -1066,6 +1066,7 @@ Translation module .. list-table:: :header-rows: 1 + :widths: 20 60 20 * - Name - Explanation diff --git a/docs/styles/dfhack.css b/docs/styles/dfhack.css index c1a00ed908..d3156b0e9a 100644 --- a/docs/styles/dfhack.css +++ b/docs/styles/dfhack.css @@ -79,3 +79,13 @@ div.dfhack-tool-summary p:last-child, aside.dfhack-tool-summary p:last-child { margin-bottom: 0; } + + +table { + table-layout: fixed; + width: 110%; +} + +table span.pre { + white-space: wrap; +} \ No newline at end of file From c8507f6edd9cec53726e8b101bc166c4d5797d8b Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 20:08:59 +0200 Subject: [PATCH 08/10] CSS formatting fix --- docs/styles/dfhack.css | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/styles/dfhack.css b/docs/styles/dfhack.css index d3156b0e9a..15b1940a6b 100644 --- a/docs/styles/dfhack.css +++ b/docs/styles/dfhack.css @@ -80,7 +80,6 @@ aside.dfhack-tool-summary p:last-child { margin-bottom: 0; } - table { table-layout: fixed; width: 110%; @@ -88,4 +87,4 @@ table { table span.pre { white-space: wrap; -} \ No newline at end of file +} From 17f18739530718f544260ce32d77ef26846db77c Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 20:27:34 +0200 Subject: [PATCH 09/10] Tweak column widths --- docs/dev/Lua API.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index cc89e3f101..842f630506 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -1066,7 +1066,7 @@ Translation module .. list-table:: :header-rows: 1 - :widths: 20 60 20 + :widths: 21 60 19 * - Name - Explanation From 2506b76ab8fe889af46df77a378a30735c0e711c Mon Sep 17 00:00:00 2001 From: agnieszka-dev Date: Sun, 19 Jul 2026 20:27:55 +0200 Subject: [PATCH 10/10] Add explicit mention that `name` is an output parameter --- docs/dev/Lua API.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 842f630506..f8ba15ff52 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -1072,7 +1072,7 @@ Translation module - Explanation - Data Type * - ``name`` - - | ``name`` property of the object that will have its name generated. + - | ``name`` property of the object that will have its name generated. This is an output parameter. | | Example values: | ``df.global.world.entities.all[0].name``