From 46d5ff9ca734adab73a57c1389b116c252fedb11 Mon Sep 17 00:00:00 2001
From: Darrell Anderson <darrella@clovermail.net>
Date: Wed, 21 May 2025 13:24:39 +0900
Subject: [PATCH] Add improved handbook text about the panel button stacking
 behavior

Signed-off-by: Darrell Anderson <darrella@clovermail.net>
Signed-off-by: Michele Calgaro <michele.calgaro@yahoo.it>
---
 doc/kicker/index.docbook       | 31 ++++++++++++++++++++++++-------
 kcontrol/kicker/positiontab.ui |  2 +-
 kicker/taskbar/taskbar.kcfg    |  8 ++++----
 3 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/doc/kicker/index.docbook b/doc/kicker/index.docbook
index 1692f8d8d..2249f928f 100644
--- a/doc/kicker/index.docbook
+++ b/doc/kicker/index.docbook
@@ -1019,14 +1019,31 @@ If there is no mark in the checkbox, then the panel is fixed to the
 length specified in this section.
 </para>
 
-<para>The final section of this table is labeled
-<guilabel>Size</guilabel>, and refers to the
-<emphasis>height</emphasis> of the panel. The panel's size can be
-<guilabel>Tiny</guilabel>, <guilabel>Small</guilabel>,
+<para>The final section of this dialog is labeled <guilabel>Size</guilabel>,
+and refers to the <emphasis>height</emphasis> of the panel. The panel's size
+can be <guilabel>Tiny</guilabel>, <guilabel>Small</guilabel>,
 <guilabel>Medium</guilabel>, <guilabel>Large</guilabel> or
-<guilabel>Custom</guilabel>. If you choose
-<guilabel>Custom</guilabel> mode, you can resize &kicker; by
-specifying a height in the combobox.</para>
+<guilabel>Custom</guilabel>. Choosing <guilabel>Custom</guilabel> mode allows
+resizing &kicker; by specifying a height in the combobox. The default
+size for the predefined <emphasis>height</emphasis> <guilabel>Tiny</guilabel>
+is 24 pixels, <guilabel>Small</guilabel> is 30 pixels,
+<guilabel>Normal</guilabel> is 46 pixels, and <guilabel>Large</guilabel> is
+58 pixels.</para>
+
+<tip><para>There are additional hidden options. These hidden options are
+configured in <guilabel>$TDEHOME/share/config/ktaskbarrc [General]</guilabel>.
+The <guilabel>MinimumButtonHeight</guilabel> option is the
+<emphasis>height</emphasis> where taskbar buttons stack into rows. The default
+value is <emphasis>18</emphasis> pixels. To prevent the taskbar buttons from
+stacking into rows, <guilabel>MinimumButtonHeight</guilabel> must defined
+explicitly and be at least one pixel larger than the defined panel
+<emphasis>height</emphasis>.</para></tip>
+
+<tip><para>A second hidden option is <guilabel>MaximumButtonWidth</guilabel>.
+The default value is <emphasis>200</emphasis> pixels. This is the
+<emphasis>width</emphasis> each taskbar button will use. To override the
+default value the option must defined explicitly. The setting mostly affects
+using a Display option with text.</para></tip>
 
 <para>If you have multiple monitors, you can configure the panel for
 each screen entirely independently. If you are not sure which screen
diff --git a/kcontrol/kicker/positiontab.ui b/kcontrol/kicker/positiontab.ui
index 2786cedf5..fb3427b03 100644
--- a/kcontrol/kicker/positiontab.ui
+++ b/kcontrol/kicker/positiontab.ui
@@ -380,7 +380,7 @@ how it is positioned on the screen and how much of the screen it should use.</st
                 <string>Si&amp;ze</string>
             </property>
             <property name="whatsThis" stdset="0">
-                <string>This sets the size of the panel.</string>
+                <string>This sets the height of the panel. Tiny is 24 pixels high, Small is 30 pixels, Normal is 46 pixels, Large is 58 pixels.</string>
             </property>
             <grid>
                 <property name="name">
diff --git a/kicker/taskbar/taskbar.kcfg b/kicker/taskbar/taskbar.kcfg
index 86ea32dca..0665470df 100644
--- a/kicker/taskbar/taskbar.kcfg
+++ b/kicker/taskbar/taskbar.kcfg
@@ -93,14 +93,14 @@
             <default>200</default>
             <min>50</min>
             <max>500</max>
-            <label>Maximum button width</label>
-            <whatsthis>The maximum width to which a taskbar item can expand.</whatsthis>
+            <label>Maximum Taskbar Button Width</label>
+            <whatsthis>The maximum width each taskbar button will use. The default value is 200 pixels. The setting affects the Display options Text only and Icons and Text.</whatsthis>
         </entry>
         <entry key="MinimumButtonHeight" type="Int" >
             <default>18</default>
-            <label></label>
+            <label>Minimum Taskbar Button Height</label>
             <min>1</min>
-            <whatsthis></whatsthis>
+            <whatsthis>The minimum height to trigger taskbar buttons to stack into rows. The default value is 18 pixels. To prevent the taskbar buttons from stacking into rows, MinimumButtonHeight must be at least one pixel larger than the defined panel height.</whatsthis>
         </entry>
         <entry key="ShowCurrentScreenOnly" type="Bool" >
             <default>false</default>