[list-waves] use historical events for better representation of actual migration record

changelog.txt

@@ -36,9 +36,12 @@ Template for new versions:
 - `gui/unit-info-viewer`: correctly display skill levels when rust is involved
 - `build-now`: fix error when building buildings that (in previous DF versions) required the architecture labor
 - `prioritize`: fix incorrect loading of persisted data on some OS types
+- `list-waves`: no longer gets confused by units that leave the map and then return (e.g. squads who go out on raids)
 
 ## Misc Improvements
 - `build-now`: if `suspendmanager` is running, run an unsuspend cycle immediately before scanning for buildings to build
+- `list-waves`: now outputs the names of the dwarves in each migration wave
+- `list-waves`: can now display information about specific migration waves (like identifying your starting 7 dwarves)
 
 ## Removed
 

docs/list-waves.rst

@@ -2,41 +2,54 @@ list-waves
 ==========
 
 .. dfhack-tool::
-    :summary: Show migration wave information.
+    :summary: Show migration wave membership and history.
     :tags: fort inspection units
 
-This script displays information about migration waves or identifies which wave
-a particular dwarf came from.
+This script displays information about past migration waves: when they arrived
+and which dwarves arrived in them. If you have a citizen selected in the UI or
+if you have passed the ``--unit`` option with a unit id, that citizen's name
+and wave will be highlighted in the output.
+
+Residents that became citizens via petitions will be grouped with any other
+dwarves that immigrated/joined at the same time.
 
 Usage
 -----
 
 ::
 
-    list-waves --all [--showarrival] [--granularity <value>]
-    list-waves --unit [--granularity <value>]
+    list-waves [<wave num> ...] [<options>]
+
+You can show only information about specific waves by specifing the wave
+numbers on the commandline. Otherwise, all waves are shown. The first migration
+wave that normally arrives in a fort's second season is wave number 1. The
+founding dwarves arrive in wave 0.
 
 Examples
 --------
 
-``list-waves --all``
-    Show how many dwarves came in each migration wave.
-``list-waves --all --showarrival``
-    Show how many dwarves came in each migration wave and when that migration
-    wave arrived.
-``list-waves --unit``
-    Show which migration wave the selected dwarf arrived with.
+``list-waves``
+    Show how many of your current dwarves came in each migration wave, when
+    the waves arrived, and the names of the dwarves in each wave.
+``list-waves --no-names``
+    Only show how many dwarves came in each seasonal migration wave and when
+    the waves arrived. Don't show the list of dwarves that came in each wave.
+``list-waves 0``
+    Identify your founding dwarves.
 
 Options
 -------
 
-``--unit``
-    Displays the highlighted unit's arrival wave information.
-``--all``
-    Displays information about each arrival wave.
-``--granularity <value>``
+``-d``, ``--no-dead``
+    Exclude residents and citizens who have died.
+``-g``, ``--granularity <value>``
     Specifies the granularity of wave enumeration: ``years``, ``seasons``,
     ``months``, or ``days``. If omitted, the default granularity is ``seasons``,
     the same as Dwarf Therapist.
-``--showarrival``:
-    Shows the arrival date for each wave.
+``-n``, ``--no-names``
+    Don't output the names of the members of each migration wave.
+``-p``, ``--no-petitioners``
+    Exclude citizens who joined via petition. That is, only show dwarves who
+    came in an actual migration wave.
+``-u``, ``--unit <id>``
+    Highlight the specified unit's arrival wave information.