[gimp-help] Add layers dock improvements

[Julien Hardlin <jhardlin src gnome org>]

commit 2f0e51b963377aec55740f04cdc60b1dab38483b
Author: Julien Hardelin <jhardlin orange fr>
Date:   Sat Apr 11 07:42:48 2020 +0200

    Add layers dock improvements

 images/C/dialogs/layer-dialog.png      | Bin 21076 -> 18254 bytes
 images/C/dialogs/merge-layers-icon.png | Bin 0 -> 466 bytes
 src/concepts/selection.xml             |   3 ++-
 src/dialogs/layer-dialog.xml           |  48 +++++++++++++++++++++++++++++----
 src/menus/select/float.xml             |   4 ++-
 5 files changed, 48 insertions(+), 7 deletions(-)
---
diff --git a/images/C/dialogs/layer-dialog.png b/images/C/dialogs/layer-dialog.png
index 7644d4dd2..06a415a55 100644
Binary files a/images/C/dialogs/layer-dialog.png and b/images/C/dialogs/layer-dialog.png differ
diff --git a/images/C/dialogs/merge-layers-icon.png b/images/C/dialogs/merge-layers-icon.png
new file mode 100644
index 000000000..a38c9b210
Binary files /dev/null and b/images/C/dialogs/merge-layers-icon.png differ
diff --git a/src/concepts/selection.xml b/src/concepts/selection.xml
index f75a9fc23..6e00fa739 100644
--- a/src/concepts/selection.xml
+++ b/src/concepts/selection.xml
@@ -188,7 +188,8 @@
             <guimenuitem>Floating</guimenuitem>
           </menuchoice>
           to create a floating selection. This creates a new layer with
-          the selection called <quote>Floating Selection</quote>.
+          the selection called <quote>Floating Selection</quote> 
+          (<xref linkend="gimp-selection-float"/>).
 
           Set the opacity slider in the Layer Dialog to the desired opacity.
           Then anchor the selection: outside the selection, the mouse pointer
diff --git a/src/dialogs/layer-dialog.xml b/src/dialogs/layer-dialog.xml
index aa9cb66b1..d94c0ebea 100644
--- a/src/dialogs/layer-dialog.xml
+++ b/src/dialogs/layer-dialog.xml
@@ -491,6 +491,15 @@
             
             <varlistentry>
               <term>
+                <guiicon>
+                  <inlinemediaobject>
+                    <imageobject>
+                      <imagedata format="PNG"
+                        fileref="images/dialogs/merge-layers-icon.png"/>
+                    </imageobject>
+                  </inlinemediaobject>
+                </guiicon>
+                <phrase>Merge layers</phrase>
                 <guiicon>
                   <inlinemediaobject>
                     <imageobject>
@@ -503,17 +512,46 @@
               </term>
               <listitem>
                 <para>
-                  When the active layer is a temporary layer (also called
-                  floating selection) shown by this icon
+                  Before GIMP-2.10.18, this button was permanently for anchoring. 
+                  Now, it becomes an anchor only when a floating selection is 
+                  created (it anchors the floating selection to the previous 
+                  active layer). Else, it is a <guibutton>Merge layers</guibutton> 
+                  icon 
                   <guiicon>
                     <inlinemediaobject>
                       <imageobject>
                         <imagedata format="PNG"
-                          fileref="images/dialogs/stock-floating-selection-16.png"/>
+                      fileref="images/dialogs/merge-layers-icon.png"/>
                       </imageobject>
                     </inlinemediaobject>
-                  </guiicon>,
-                  this button anchors it to the previous active layer.
+                  </guiicon>
+                  with several possibilities:
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        Merge this layer with the first visible layer below it.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        Pressing <keycap>Shift</keycap>: merge the layer group's 
+                        layers into one normal layer.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        Pressing <keycap>Ctrl</keycap>: merge all visible layers 
+                        into one normal layer.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        Pressing 
+                <keycombo><keycap>Shift</keycap><keycap>Ctrl</keycap></keycombo>:
+                        merge all visible layers with last used values.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </para>
               </listitem>
             </varlistentry>
diff --git a/src/menus/select/float.xml b/src/menus/select/float.xml
index f5f9dfaca..c0ad0252d 100644
--- a/src/menus/select/float.xml
+++ b/src/menus/select/float.xml
@@ -153,7 +153,9 @@
               </textobject>
             </inlinemediaobject>
           </guiicon>
-          of the <link linkend="gimp-layer-dialog">Layers dialog</link>.
+          of the <link linkend="gimp-layer-dialog">Layers dialog</link>, that 
+          appears, since GIMP-2.10.18, when the floating selection is created, 
+          instead of the default Merge layers icon.
         </para>
       </listitem>
       <listitem>