[gimp-help] Fix #347 Incorrect change in layer group examples

[Jacob Boerema <jboerema src gnome org>]

commit 3224a68511a7be11b0759f38d132300d1776d3c5
Author: Jacob Boerema <jgboerema gmail com>
Date:   Sat Sep 10 21:40:05 2022 -0400

    Fix #347 Incorrect change in layer group examples
    
    We correct and update the layer groups documentation.
    The layer mode Saturation, used in the example, did not exist anymore.
    We replace it with the closest similar mode HSL Color.
    Also add the xcf used to create the sample images.
    
    # Conflicts:
    #       src/concepts/layer-groups.xml

 images/C/dialogs/layer-group-mask.png      | Bin 8357 -> 20164 bytes
 images/C/dialogs/layer-group-merge-in.png  | Bin 7985 -> 24128 bytes
 images/C/dialogs/layer-group-merge-out.png | Bin 7917 -> 23952 bytes
 images/C/dialogs/layer-group-original.png  | Bin 2867 -> 4628 bytes
 images/C/dialogs/layer-group.png           | Bin 9673 -> 17390 bytes
 src/concepts/layer-groups.xml              |  97 +++++++++++++++--------------
 src/images/dialogs/layer-groups.xcf        | Bin 0 -> 16626 bytes
 7 files changed, 49 insertions(+), 48 deletions(-)
---
diff --git a/images/C/dialogs/layer-group-mask.png b/images/C/dialogs/layer-group-mask.png
index 81dd9bb39..54c286f63 100644
Binary files a/images/C/dialogs/layer-group-mask.png and b/images/C/dialogs/layer-group-mask.png differ
diff --git a/images/C/dialogs/layer-group-merge-in.png b/images/C/dialogs/layer-group-merge-in.png
index 2af817a72..4ec8acfaf 100644
Binary files a/images/C/dialogs/layer-group-merge-in.png and b/images/C/dialogs/layer-group-merge-in.png 
differ
diff --git a/images/C/dialogs/layer-group-merge-out.png b/images/C/dialogs/layer-group-merge-out.png
index 4e6b2b48f..bf2bf0526 100644
Binary files a/images/C/dialogs/layer-group-merge-out.png and b/images/C/dialogs/layer-group-merge-out.png 
differ
diff --git a/images/C/dialogs/layer-group-original.png b/images/C/dialogs/layer-group-original.png
index 90e0c82a4..8d2514a87 100644
Binary files a/images/C/dialogs/layer-group-original.png and b/images/C/dialogs/layer-group-original.png 
differ
diff --git a/images/C/dialogs/layer-group.png b/images/C/dialogs/layer-group.png
index 4df8c79f3..b6a161396 100644
Binary files a/images/C/dialogs/layer-group.png and b/images/C/dialogs/layer-group.png differ
diff --git a/src/concepts/layer-groups.xml b/src/concepts/layer-groups.xml
index 0c3466568..ad2ff1460 100644
--- a/src/concepts/layer-groups.xml
+++ b/src/concepts/layer-groups.xml
@@ -21,12 +21,9 @@
   </indexterm>
 
   <para>
-    Layer Groups are available in <acronym>GIMP</acronym> 2.8 and newer.
-  </para>
-
-  <para>
-    You can group layers that have similarities in a tree-like way. So, the
-    layer list becomes easier to manage.
+    <quote>Layer Groups</quote> enable you to group layers together in a
+    hierarchical structure. This will make it easier to manage your project
+    if you have many layers.
   </para>
 
   <mediaobject>
@@ -42,11 +39,9 @@
       <listitem>
         <para>
           You can create a layer group by clicking the
-          <guibutton>New Layer Group</guibutton>
-          button at the bottom of the layers dialog,
-        </para>
-        <para>
-          through
+          <guibutton>New Layer Group</guibutton> button at the bottom of the
+          <ulink url="gimp-layer-dialog">Layers Dialog</ulink>,
+          by using the menu command
           <menuchoice>
             <guimenu>Layer</guimenu>
             <guimenuitem>New Layer Group</guimenuitem>
@@ -54,16 +49,17 @@
           or through the Layers dialog context menu.
         </para>
         <para>
-          This empty layer group appears just above the current layer. It is
-          recommended to give it a name that is descriptive.  To change
-          the layer group name, double-click the name, or press 
-          <keycap>F2</keycap> the name, or right-click it and then select
-          the <command>Edit Layer Attributes</command> in the context menu.
-          If you don't rename your layer groups, you will get confused when several 
-          are created with names such as Layer Group #1, Layer Group #2, etc.
+          This new empty layer group appears just above the current layer. It is
+          recommended to give it a descriptive name. To change the layer group
+          name, double-click the name, press <keycap>F2</keycap>, or
+          right-click the layer and select
+          <command>Edit Layer Attributes</command> from the context menu.
+          If you don't rename your layer groups, you can get confused when
+          several groups have been created with names such as Layer Group #1,
+          Layer Group #2, etc.
         </para>
         <para>
-          You can create several layer groups and you can
+          You can create multiple layer groups and you can
           <emphasis role="bold">embed</emphasis> them, that is include a
           layer group in another one.
         </para>
@@ -82,22 +78,21 @@
               before releasing the mouse button.
             </para>
             <para>
-              A thin horizontal line marks where the layer will be laid
-              down.
+              A thin horizontal line marks where the layer will be inserted.
             </para>
           </note>
         </para>
         <para>
           To add a <emphasis>new layer</emphasis> to the current layer
           group,
-          click the <guibutton>New Layer...</guibutton> at the
-          bottom of the Layers dialog, or use the
-          <guimenuitem>New Layer</guimenuitem> command in the image menu
+          click the <guibutton>New Layer...</guibutton> button at the
+          bottom of the Layers dialog, use the
+          <guimenuitem>New Layer...</guimenuitem> command in the image menu,
           or press <keycombo><keycap>Shift</keycap><keycap>Ctrl</keycap><keycap>N</keycap></keycombo>.
         </para>
         <para>
-          When a layer group is not empty, a small <quote>></quote> icon
-          appears. By clicking it, you can fold or unfold the layer list.
+          When a layer group is not empty, a small icon appears. By clicking
+          it, you can fold or unfold the group.
           <mediaobject>
             <imageobject>
               <imagedata format="PNG"
@@ -107,7 +102,7 @@
         </para>
         <para>
           Layers that belong to a layer group are slightly indented to the
-          right, allowing you know easily which layers are part of the
+          right, allowing you to easily see which layers are part of the
           group.
         </para>
       </listitem>
@@ -195,7 +190,7 @@
         <para>
           When a layer group is activated, you can add another group inside
           it with the <quote>Add New Layer Group</quote> command. There
-          seems to be no limit, excepted memory, to the number of embedded
+          seems to be no limit, except memory, to the number of embedded
           layer groups.
         </para>
       </listitem>
@@ -230,7 +225,7 @@
             <caption>
               <para>
                 We added a white layer <emphasis>in</emphasis> the layer group
-                with saturation mode: only square and triangle are disabled.
+                with HSL Color mode: only the square and triangle turned gray.
               </para>
             </caption>
           </mediaobject>
@@ -241,16 +236,16 @@
             </imageobject>
             <caption>
               <para>
-                We added a white layer <emphasis>out</emphasis> of the layer
-                group with saturation mode: all layers underneath are disabled, 
-                including the background layer.
+                We added a white layer <emphasis>outside</emphasis> and above
+                the layer group with HSL Color mode: all layers underneath
+                changed to gray, including the background layer.
               </para>
             </caption>
           </mediaobject>
         </figure>
         
         <para>
-          With <acronym>GIMP</acronym> 2.10 and newer, layer groups have a special layer mode: the 
+          Since <acronym>GIMP</acronym> 2.10, layer groups have a special layer mode: the 
           <guilabel>Pass Through</guilabel> mode. This mode exists only if a 
           layer group is active.
         </para>
@@ -287,15 +282,17 @@
       <term>Layer Mask</term>
       <listitem>
         <para>
-                                       With <acronym>GIMP</acronym> 2.10 and newer, masks on layer groups 
are possible. They work similarly to 
-                                       ordinary-layer masks, with the following considerations.
+          Since <acronym>GIMP</acronym> 2.10, masks on layer groups are possible.
+          They work similarly to ordinary layer masks, with the following
+          considerations.
                                </para>
                                <para>
-                                       The group’s mask size is the same as group’s size (i.e., the bounding 
box of its children) at all times. When the group’s size changes, the mask is cropped to the new size — areas 
of the mask that fall outside of the new bounds are discarded, and newly added areas are filled with black 
(and hence are transparent by default).
+          The layer group’s mask size is the same as the combined size of all
+          its children at all times. When the group’s size changes, the
+          mask is cropped to the new size — areas of the mask that fall outside
+          of the new bounds are discarded, and newly added areas are filled with
+          black (and hence are transparent by default).
                                </para>
-                               <para>
-                                        Of course, you still can add a layer mask to a layer in the group to 
mask a part of the layer:
-        </para>
         <mediaobject>
           <imageobject>
             <imagedata format="PNG"
@@ -303,10 +300,15 @@
           </imageobject>
           <caption>
             <para>
-              We added a white (Full opacity) layer mask to the triangle layer.
+              We added a black (transparent) layer mask to the layer group,
+              making the layers inside the group transparent (invisible).
             </para>
           </caption>
         </mediaobject>
+        <para>
+          Of course, you still can add a layer mask to a layer in the group to
+          mask a part of the layer.
+        </para>
       </listitem>
     </varlistentry>
     
@@ -315,11 +317,11 @@
       <listitem>
         <para>
           When working with a lot of layers, finding a particular layer in the 
-          list may be difficult. With <acronym>GIMP</acronym> 2.10.10 and newer, a new 
+          list can be difficult. Since <acronym>GIMP</acronym> 2.10.10, a new 
           <emphasis>on-canvas layer selection</emphasis> function is available. 
-          <keycombo><keycap>Alt</keycap><mousebutton>middle click</mousebutton>
-          </keycombo> the image element you want to find the layer this 
-          element belongs to: the available layers will be looped through to 
+          Use <keycombo><keycap>Alt</keycap><keycap>Middle click</keycap>
+          </keycombo> on the image element you want to find the layer this 
+          element belongs to. The available layers will be looped through to 
           show the new active layer and the layer name will be temporarily 
           displayed in the status bar.
         </para>
@@ -329,10 +331,9 @@
       <term>Layer preview</term>
       <listitem>
         <para>
-          There were problems with drawable preview rendering in the case of a 
-          large image consisting of many layers. This problem is fixed with
-          <acronym>GIMP</acronym> 2.10.10 and newer, except for layer 
-          groups. You can disable rendering layer group previews in 
+          There have been problems with slow preview rendering of layer
+          groups in case of many layers in a large image. If you are
+          experiencing this, you can disable rendering layer group previews in 
           <menuchoice>
             <guimenu>Edit</guimenu>
             <guisubmenu>Preferences</guisubmenu>
diff --git a/src/images/dialogs/layer-groups.xcf b/src/images/dialogs/layer-groups.xcf
new file mode 100644
index 000000000..516f82c81
Binary files /dev/null and b/src/images/dialogs/layer-groups.xcf differ