From 50a447061da9652577a3cb11a304d4fedb937d02 Mon Sep 17 00:00:00 2001
From: Myk Taylor <myk002@yahoo.com>
Date: Sat, 30 Dec 2023 20:17:01 -0800
Subject: [PATCH 1/3] add desc as an official Overlay API property

---
 docs/dev/overlay-dev-guide.rst | 5 ++++-
 plugins/lua/overlay.lua        | 2 ++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/dev/overlay-dev-guide.rst b/docs/dev/overlay-dev-guide.rst
index b5b6cf0e3..2ef07ec04 100644
--- a/docs/dev/overlay-dev-guide.rst
+++ b/docs/dev/overlay-dev-guide.rst
@@ -89,11 +89,14 @@ The ``overlay.OverlayWidget`` superclass defines the following class attributes:
 - ``name``
     This will be filled in with the display name of your widget, in case you
     have multiple widgets with the same implementation but different
-    configurations.
+    configurations. You should not set this property yourself.
 - ``version``
     You can set this to any string. If the version string of a loaded widget
     does not match the saved settings for that widget, then the configuration
     for the widget (position, enabled status) will be reset to defaults.
+- ``desc``
+    A short (<100 character) description of what the overlay does. This text
+    will be displayed in `gui/control-panel` on the "Overlays" tab.
 - ``default_pos`` (default: ``{x=-2, y=-2}``)
     Override this attribute with your desired default widget position. See
     the `overlay` docs for information on what positive and negative numbers
diff --git a/plugins/lua/overlay.lua b/plugins/lua/overlay.lua
index d8b3c4f81..9084e50b2 100644
--- a/plugins/lua/overlay.lua
+++ b/plugins/lua/overlay.lua
@@ -553,6 +553,7 @@ end
 OverlayWidget = defclass(OverlayWidget, widgets.Panel)
 OverlayWidget.ATTRS{
     name=DEFAULT_NIL, -- this is set by the framework to the widget name
+    desc=DEFAULT_NIL, -- add a short description (<100 chars); displays in control panel
     default_pos={x=DEFAULT_X_POS, y=DEFAULT_Y_POS}, -- 1-based widget screen pos
     default_enabled=false, -- initial enabled state if not in config
     overlay_only=false, -- true if there is no widget to reposition
@@ -581,6 +582,7 @@ end
 
 TitleVersionOverlay = defclass(TitleVersionOverlay, OverlayWidget)
 TitleVersionOverlay.ATTRS{
+    desc='Show DFHack version number and quick links on the DF title page.',
     default_pos={x=11, y=1},
     version=2,
     default_enabled=true,

From 80f9fea5227c111f3ddb217238d1ee3c7280f31b Mon Sep 17 00:00:00 2001
From: Myk Taylor <myk002@yahoo.com>
Date: Sat, 30 Dec 2023 21:24:11 -0800
Subject: [PATCH 2/3] add descriptions to all plugin overlays

---
 plugins/lua/autolabor.lua                     | 1 +
 plugins/lua/buildingplan/inspectoroverlay.lua | 1 +
 plugins/lua/buildingplan/mechanisms.lua       | 1 +
 plugins/lua/buildingplan/planneroverlay.lua   | 1 +
 plugins/lua/burrow.lua                        | 1 +
 plugins/lua/dig.lua                           | 2 ++
 plugins/lua/hotkeys.lua                       | 1 +
 plugins/lua/orders.lua                        | 2 ++
 plugins/lua/sort.lua                          | 2 ++
 plugins/lua/sort/diplomacy.lua                | 2 ++
 plugins/lua/sort/info.lua                     | 4 ++++
 plugins/lua/sort/locationselector.lua         | 1 +
 plugins/lua/sort/places.lua                   | 1 +
 plugins/lua/sort/slab.lua                     | 1 +
 plugins/lua/sort/unitselector.lua             | 1 +
 plugins/lua/sort/world.lua                    | 1 +
 plugins/lua/stockpiles.lua                    | 1 +
 plugins/lua/stocks.lua                        | 1 +
 plugins/lua/zone.lua                          | 2 ++
 19 files changed, 27 insertions(+)

diff --git a/plugins/lua/autolabor.lua b/plugins/lua/autolabor.lua
index a2c0e88cd..18ccdc4a6 100644
--- a/plugins/lua/autolabor.lua
+++ b/plugins/lua/autolabor.lua
@@ -6,6 +6,7 @@ local widgets = require('gui.widgets')
 
 AutolaborOverlay = defclass(AutolaborOverlay, overlay.OverlayWidget)
 AutolaborOverlay.ATTRS{
+    desc='Adds information to the work details screen about whether work details are enabled.',
     default_pos={x=7,y=-13},
     default_enabled=true,
     viewscreens='dwarfmode/Info/LABOR/WORK_DETAILS',
diff --git a/plugins/lua/buildingplan/inspectoroverlay.lua b/plugins/lua/buildingplan/inspectoroverlay.lua
index 3c6f0ed5e..c9275d736 100644
--- a/plugins/lua/buildingplan/inspectoroverlay.lua
+++ b/plugins/lua/buildingplan/inspectoroverlay.lua
@@ -63,6 +63,7 @@ end
 
 InspectorOverlay = defclass(InspectorOverlay, overlay.OverlayWidget)
 InspectorOverlay.ATTRS{
+    desc='Adds information to planned buildings about what materials are still needed.',
     default_pos={x=-41,y=14},
     default_enabled=true,
     viewscreens='dwarfmode/ViewSheets/BUILDING',
diff --git a/plugins/lua/buildingplan/mechanisms.lua b/plugins/lua/buildingplan/mechanisms.lua
index 09957873b..081b4ecb3 100644
--- a/plugins/lua/buildingplan/mechanisms.lua
+++ b/plugins/lua/buildingplan/mechanisms.lua
@@ -13,6 +13,7 @@ local view_sheets = df.global.game.main_interface.view_sheets
 
 MechanismOverlay = defclass(MechanismOverlay, overlay.OverlayWidget)
 MechanismOverlay.ATTRS{
+    desc='Adds mechanism selection capabilities to the link lever/pressure plate screens.',
     default_pos={x=5,y=5},
     default_enabled=true,
     viewscreens='dwarfmode/LinkingLever',
diff --git a/plugins/lua/buildingplan/planneroverlay.lua b/plugins/lua/buildingplan/planneroverlay.lua
index b4e0dc90b..8836cded2 100644
--- a/plugins/lua/buildingplan/planneroverlay.lua
+++ b/plugins/lua/buildingplan/planneroverlay.lua
@@ -351,6 +351,7 @@ end
 
 PlannerOverlay = defclass(PlannerOverlay, overlay.OverlayWidget)
 PlannerOverlay.ATTRS{
+    desc='Shows the building planner interface panel when building buildings.',
     default_pos={x=5,y=9},
     default_enabled=true,
     viewscreens='dwarfmode/Building/Placement',
diff --git a/plugins/lua/burrow.lua b/plugins/lua/burrow.lua
index 42257dc50..58b91645d 100644
--- a/plugins/lua/burrow.lua
+++ b/plugins/lua/burrow.lua
@@ -52,6 +52,7 @@ end
 
 BurrowDesignationOverlay = defclass(BurrowDesignationOverlay, overlay.OverlayWidget)
 BurrowDesignationOverlay.ATTRS{
+    desc='Adds flood fill and 3D box select functionality to burrow designations.',
     default_pos={x=6,y=9},
     viewscreens='dwarfmode/Burrow/Paint',
     default_enabled=true,
diff --git a/plugins/lua/dig.lua b/plugins/lua/dig.lua
index e24885c08..b8c330a7c 100644
--- a/plugins/lua/dig.lua
+++ b/plugins/lua/dig.lua
@@ -5,6 +5,7 @@ local pathable = require('plugins.pathable')
 
 WarmDampOverlay = defclass(WarmDampOverlay, overlay.OverlayWidget)
 WarmDampOverlay.ATTRS{
+    desc='Makes warm and damp tiles visible when in ASCII mode.',
     viewscreens={
         'dwarfmode/Designate/DIG_DIG',
         'dwarfmode/Designate/DIG_REMOVE_STAIRS_RAMPS',
@@ -26,6 +27,7 @@ end
 
 CarveOverlay = defclass(CarveOverlay, overlay.OverlayWidget)
 CarveOverlay.ATTRS{
+    desc='Makes existing carving designations visible when in ASCII mode.',
     viewscreens={
         'dwarfmode/Designate/SMOOTH',
         'dwarfmode/Designate/ENGRAVE',
diff --git a/plugins/lua/hotkeys.lua b/plugins/lua/hotkeys.lua
index 4c33f93ca..a7d0c8b89 100644
--- a/plugins/lua/hotkeys.lua
+++ b/plugins/lua/hotkeys.lua
@@ -27,6 +27,7 @@ end
 
 HotspotMenuWidget = defclass(HotspotMenuWidget, overlay.OverlayWidget)
 HotspotMenuWidget.ATTRS{
+    desc='Shows the DFHack logo context menu button.',
     default_pos={x=5,y=1},
     default_enabled=true,
     version=2,
diff --git a/plugins/lua/orders.lua b/plugins/lua/orders.lua
index d01ad79be..b58566765 100644
--- a/plugins/lua/orders.lua
+++ b/plugins/lua/orders.lua
@@ -68,6 +68,7 @@ end
 
 OrdersOverlay = defclass(OrdersOverlay, overlay.OverlayWidget)
 OrdersOverlay.ATTRS{
+    desc='Adds import, export, and other functions to the manager orders screen.',
     default_pos={x=53,y=-6},
     default_enabled=true,
     viewscreens='dwarfmode/Info/WORK_ORDERS/Default',
@@ -198,6 +199,7 @@ local focusString = 'dwarfmode/Info/WORK_ORDERS/Conditions'
 
 RecheckOverlay = defclass(RecheckOverlay, overlay.OverlayWidget)
 RecheckOverlay.ATTRS{
+    desc='Adds a button to the work order details page to tell the manager to recheck conditions.',
     default_pos={x=6,y=8},
     default_enabled=true,
     viewscreens=focusString,
diff --git a/plugins/lua/sort.lua b/plugins/lua/sort.lua
index 79e91ba92..0c5058f44 100644
--- a/plugins/lua/sort.lua
+++ b/plugins/lua/sort.lua
@@ -636,6 +636,7 @@ end
 
 SquadAssignmentOverlay = defclass(SquadAssignmentOverlay, overlay.OverlayWidget)
 SquadAssignmentOverlay.ATTRS{
+    desc='Adds search, sort, and filter capabilities to the squad assignment screen.',
     default_pos={x=18, y=5},
     default_enabled=true,
     viewscreens='dwarfmode/UnitSelector/SQUAD_FILL_POSITION',
@@ -1198,6 +1199,7 @@ end
 
 SquadAnnotationOverlay = defclass(SquadAnnotationOverlay, overlay.OverlayWidget)
 SquadAnnotationOverlay.ATTRS{
+    desc='Annotates squad selection candidates with the values of the current sort.',
     default_pos={x=56, y=5},
     default_enabled=true,
     viewscreens='dwarfmode/UnitSelector/SQUAD_FILL_POSITION',
diff --git a/plugins/lua/sort/diplomacy.lua b/plugins/lua/sort/diplomacy.lua
index 1ea7a27e9..c0ec81850 100644
--- a/plugins/lua/sort/diplomacy.lua
+++ b/plugins/lua/sort/diplomacy.lua
@@ -12,6 +12,7 @@ local diplomacy = df.global.game.main_interface.diplomacy
 
 DiplomacyOverlay = defclass(DiplomacyOverlay, sortoverlay.SortOverlay)
 DiplomacyOverlay.ATTRS{
+    desc='Adds search and sort functionality to the elevate unit to barony screen.',
     default_pos={x=25, y=7},
     viewscreens='dwarfmode/Diplomacy',
     frame={w=57, h=1},
@@ -110,6 +111,7 @@ end
 
 PreferenceOverlay = defclass(PreferenceOverlay, overlay.OverlayWidget)
 PreferenceOverlay.ATTRS{
+    desc='Adds information about unit preferences to the elevate unit to barony screen.',
     default_pos={x=-34, y=9},
     viewscreens='dwarfmode/Diplomacy/ElevateLandHolder',
     default_enabled=true,
diff --git a/plugins/lua/sort/info.lua b/plugins/lua/sort/info.lua
index cb05bae7b..5747713ae 100644
--- a/plugins/lua/sort/info.lua
+++ b/plugins/lua/sort/info.lua
@@ -190,6 +190,7 @@ end
 
 InfoOverlay = defclass(InfoOverlay, sortoverlay.SortOverlay)
 InfoOverlay.ATTRS{
+    desc='Adds search and filter functionality to most info panels.',
     default_pos={x=64, y=8},
     viewscreens='dwarfmode/Info',
     frame={w=40, h=6},
@@ -493,6 +494,7 @@ end
 
 CandidatesOverlay = defclass(CandidatesOverlay, sortoverlay.SortOverlay)
 CandidatesOverlay.ATTRS{
+    desc='Adds search functionality to the noble assignment page.',
     default_pos={x=54, y=8},
     viewscreens='dwarfmode/Info/ADMINISTRATORS/Candidates',
     frame={w=27, h=3},
@@ -547,6 +549,7 @@ end
 
 WorkAnimalOverlay = defclass(WorkAnimalOverlay, overlay.OverlayWidget)
 WorkAnimalOverlay.ATTRS{
+    desc='Annotates units with how many work animals they have assigned on the assign work animal screen.',
     default_pos={x=-33, y=12},
     viewscreens='dwarfmode/Info/CREATURES/AssignWorkAnimal',
     default_enabled=true,
@@ -617,6 +620,7 @@ end
 
 InterrogationOverlay = defclass(InterrogationOverlay, sortoverlay.SortOverlay)
 InterrogationOverlay.ATTRS{
+    desc='Adds search and filter capabilities to the justice screens.',
     default_pos={x=47, y=10},
     viewscreens='dwarfmode/Info/JUSTICE',
     frame={w=27, h=9},
diff --git a/plugins/lua/sort/locationselector.lua b/plugins/lua/sort/locationselector.lua
index f4a707073..32177c366 100644
--- a/plugins/lua/sort/locationselector.lua
+++ b/plugins/lua/sort/locationselector.lua
@@ -11,6 +11,7 @@ local location_selector = df.global.game.main_interface.location_selector
 
 LocationSelectorOverlay = defclass(LocationSelectorOverlay, sortoverlay.SortOverlay)
 LocationSelectorOverlay.ATTRS{
+    desc='Adds search and filter capabilities to the temple and guildhall establishment screens.',
     default_pos={x=48, y=6},
     viewscreens='dwarfmode/LocationSelector',
     frame={w=26, h=3},
diff --git a/plugins/lua/sort/places.lua b/plugins/lua/sort/places.lua
index 08f4e4f1c..a3a2fd03f 100644
--- a/plugins/lua/sort/places.lua
+++ b/plugins/lua/sort/places.lua
@@ -147,6 +147,7 @@ end
 
 PlacesOverlay = defclass(PlacesOverlay, sortoverlay.SortOverlay)
 PlacesOverlay.ATTRS{
+    desc='Adds search functionality to the places overview screens.',
     default_pos={x=71, y=9},
     viewscreens='dwarfmode/Info',
     frame={w=40, h=6}
diff --git a/plugins/lua/sort/slab.lua b/plugins/lua/sort/slab.lua
index 5945763c9..a03c71d37 100644
--- a/plugins/lua/sort/slab.lua
+++ b/plugins/lua/sort/slab.lua
@@ -12,6 +12,7 @@ local building = df.global.game.main_interface.building
 
 SlabOverlay = defclass(SlabOverlay, sortoverlay.SortOverlay)
 SlabOverlay.ATTRS{
+    desc='Adds search and filter functionality to the slab engraving panel.',
     default_pos={x=-40, y=12},
     viewscreens='dwarfmode/ViewSheets/BUILDING/Workshop',
     frame={w=57, h=3},
diff --git a/plugins/lua/sort/unitselector.lua b/plugins/lua/sort/unitselector.lua
index 37617a102..c5a3387c3 100644
--- a/plugins/lua/sort/unitselector.lua
+++ b/plugins/lua/sort/unitselector.lua
@@ -16,6 +16,7 @@ local WIDGET_WIDTH = 31
 
 UnitSelectorOverlay = defclass(UnitSelectorOverlay, sortoverlay.SortOverlay)
 UnitSelectorOverlay.ATTRS{
+    desc='Adds search functionality to the unit assignment screens.',
     default_pos={x=62, y=6},
     viewscreens='dwarfmode/UnitSelector',
     frame={w=31, h=1},
diff --git a/plugins/lua/sort/world.lua b/plugins/lua/sort/world.lua
index 65263cb98..00e7e6158 100644
--- a/plugins/lua/sort/world.lua
+++ b/plugins/lua/sort/world.lua
@@ -9,6 +9,7 @@ local widgets = require('gui.widgets')
 
 WorldOverlay = defclass(WorldOverlay, sortoverlay.SortOverlay)
 WorldOverlay.ATTRS{
+    desc='Adds search functionality to the artifact list on the world raid screen.',
     default_pos={x=-18, y=2},
     viewscreens='world/ARTIFACTS',
     frame={w=40, h=1},
diff --git a/plugins/lua/stockpiles.lua b/plugins/lua/stockpiles.lua
index 1173fa2d9..9740929ec 100644
--- a/plugins/lua/stockpiles.lua
+++ b/plugins/lua/stockpiles.lua
@@ -394,6 +394,7 @@ end
 
 StockpilesOverlay = defclass(StockpilesOverlay, overlay.OverlayWidget)
 StockpilesOverlay.ATTRS{
+    desc='Shows a panel when a stockpile is selected for stockpile automation.',
     default_pos={x=24, y=-6},
     default_enabled=true,
     viewscreens='dwarfmode/Some/Stockpile',
diff --git a/plugins/lua/stocks.lua b/plugins/lua/stocks.lua
index b87052530..78257261e 100644
--- a/plugins/lua/stocks.lua
+++ b/plugins/lua/stocks.lua
@@ -20,6 +20,7 @@ end
 
 StocksOverlay = defclass(StocksOverlay, overlay.OverlayWidget)
 StocksOverlay.ATTRS{
+    desc='Adds a hotkey for collapse all to the stocks page.',
     default_pos={x=-3,y=-20},
     default_enabled=true,
     viewscreens='dwarfmode/Stocks',
diff --git a/plugins/lua/zone.lua b/plugins/lua/zone.lua
index eb984093b..7cce19a37 100644
--- a/plugins/lua/zone.lua
+++ b/plugins/lua/zone.lua
@@ -835,6 +835,7 @@ end
 
 PasturePondOverlay = defclass(PasturePondOverlay, overlay.OverlayWidget)
 PasturePondOverlay.ATTRS{
+    desc='Adds a link to launch the animal assignment UI to pastures and ponds.',
     default_pos={x=7,y=13},
     default_enabled=true,
     viewscreens={'dwarfmode/Zone/Some/Pen', 'dwarfmode/Zone/Some/Pond'},
@@ -952,6 +953,7 @@ end
 
 CageChainOverlay = defclass(CageChainOverlay, overlay.OverlayWidget)
 CageChainOverlay.ATTRS{
+    desc='Adds a link to launch the animal assignment UI to cages and chains.',
     default_pos={x=-40,y=34},
     default_enabled=true,
     viewscreens={'dwarfmode/ViewSheets/BUILDING/Cage', 'dwarfmode/ViewSheets/BUILDING/Chain'},

From fa6ccd686e07acc031a68cd7aa536ab6a6b2dcfb Mon Sep 17 00:00:00 2001
From: Myk Taylor <myk002@yahoo.com>
Date: Sat, 30 Dec 2023 21:24:22 -0800
Subject: [PATCH 3/3] update scripts ref

---
 scripts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts b/scripts
index 1880f4a9d..596cd5f64 160000
--- a/scripts
+++ b/scripts
@@ -1 +1 @@
-Subproject commit 1880f4a9d528f8ae3a39b619bca89520185061ef
+Subproject commit 596cd5f64ad1759e390cf12cdd97e2698f6bd3b3