Merge pull request #1364 from myk002/myk_rename

new tool: `gui/rename`

Author: myk002

changelog.txt

@@ -28,10 +28,12 @@ Template for new versions:
 
 ## New Tools
 - `fix/stuck-squad`: allow squads and messengers returning from missions to rescue squads that have gotten stuck on the world map
+- `gui/rename`: (reinstated) give new in-game language-based names to anything that can be named (e.g. units, governments, fortresses, or the world)
 
 ## New Features
 - `gui/settings-manager`: new overlay on the Labor -> Standing Orders tab for configuring the number of barrels to reserve for job use (so you can brew alcohol and not have all your barrels claimed by stockpiles for container storage)
 - `gui/settings-manager`: standing orders save/load now includes the reserved barrels setting
+- `gui/rename`: add overlay to worldgen screen allowing you to rename the world before the new world is saved
 
 ## Fixes
 - `fix/dry-buckets`: don't empty buckets for wells that are actively in use

docs/gui/rename.rst

@@ -2,28 +2,96 @@ gui/rename
 ==========
 
 .. dfhack-tool::
-    :summary: Give buildings and units new names, optionally with special chars.
-    :tags: unavailable
+    :summary: Edit in-game language-based names.
+    :tags: adventure fort productivity animals items units
 
-Once you select a target on the game map, this tool allows you to rename it. It
-is more powerful than the in-game rename functionality since it allows you to
-use special characters (like diamond symbols), and it also allows you to rename
-enemies and overwrite animal species strings.
+Once you select a target (by clicking on something on the game map, by passing
+a commandline parameter, or by using the selection dialog) this tool allows you
+change the language of the name, generate a new random name, or replace
+components of the name with your preferred words.
 
-This tool supports renaming units, zones, stockpiles, workshops, furnaces,
-traps, and siege engines.
+`gui/rename` provides an interface similar to the in-game naming panel that you
+can use to customize your fortress name at embark. That is, it allows you to
+choose words from an in-game language to assemble a name, just like the default
+names that the game generates. You will be able to assign units new given and
+last names, or even rename the world itself.
+
+You can run `gui/rename` while on the "prepare carefully" embark screen to
+rename your starting dwarves.
+
+Start typing to search for a word. You can search in English, in the selected
+native language, or by the part of speech. Click on a word to assign it to the
+selected name component slot. You can also clear or randomize each individual
+name component slot.
+
+When giving a name to a unit that didn't previously have a name, you must
+assign a word to the First Name slot. Otherwise, the game will not display the
+name for the unit.
 
 Usage
 -----
 
+::
+
+    gui/rename [<options>]
+
+The selection dialog will appear if no options are provided. You can
+interactively choose one of the following to rename:
+
+- An artifact on the current map
+- A location (e.g. tavern, hospital, guildhall, temple) on the current map
+- The current fortress (or adventurer site)
+- A squad belonging to the current fortress
+- A unit on the current map
+- The world
+
+Examples
+--------
+
 ``gui/rename``
-    Renames the selected building, zone, or unit.
-``gui/rename unit-profession``
-    Set the unit profession or the animal species string.
+    Load the selected artifact, location, or unit for renaming. If nothing is
+    selected, you can select a target from a list.
+``gui/rename -u 123 --no-target-selector``
+    Load the unit with id ``123`` for renaming and remove the widget that
+    allows selecting a different target.
+``gui/rename --location 2 --site 456``
+    Load the location with "abstract building" ID ``2`` attached to the site
+    with id ``456`` for renaming.
+
+Options
+-------
+
+Targets specified via these options do not need to be on the local map.
+
+``-a``, ``--artifact <id>``
+    Rename the artifact with the given item ID.
+``-e``, ``--entity <id>``
+    Rename the historical entity (e.g. site government, world religion, etc)
+    with the given ID.
+``-f``, ``--histfig <id>``
+    Rename the historical figure with the given ID.
+``-l``, ``--location <id>``
+    Rename the location (e.g. tavern, hospital, guildhall, temple) with the
+    given ID. If this option is used, ``--site`` can be specified to indicate
+    locations attached to a specific site. If ``--site`` is not specified, the
+    location will be loaded from the current site.
+``-q``, ``--squad <id>``
+    Rename the squad with the given ID.
+``-s``, ``--site <id>``
+    Rename the site with the given ID.
+``-u``, ``--unit <id>``
+    Rename the unit with the given ID. Renaming a unit also renames the
+    associated historical figure.
+``-w``, ``--world``
+    Rename the current world.
+``--no-target-selector``
+    Do not allow the player to switch naming targets. An option that sets the
+    initial target is required when using this option.
 
-Screenshots
------------
+Overlays
+--------
 
-.. image:: /docs/images/rename-bld.png
+This tool supports the following overlays:
 
-.. image:: /docs/images/rename-prof.png
+``gui/rename.world``
+    Adds a widget to the world generation screen for renaming the world.