[gimp-help] Rewrite toolbox/free.xml

[Julien Hardlin <jhardlin src gnome org>]

commit ccefcc1649d79a18672372b34f0121615ebf8e95
Author: Julien Hardelin <jhardlin orange fr>
Date:   Tue Feb 5 18:51:38 2019 +0100

    Rewrite toolbox/free.xml

 src/filters/artistic/waterpixels.xml | 32 ++++++++------
 src/toolbox/selection/free.xml       | 82 ++++++++++++++++++++++++------------
 2 files changed, 74 insertions(+), 40 deletions(-)
---
diff --git a/src/filters/artistic/waterpixels.xml b/src/filters/artistic/waterpixels.xml
index 4d2a08239..945bac217 100644
--- a/src/filters/artistic/waterpixels.xml
+++ b/src/filters/artistic/waterpixels.xml
@@ -59,27 +59,35 @@ referring directly to algorithm and not to wanted action.
       </varlistentry>
       <varlistentry>
         <term>Superpixels size</term>
-        <para>
-          TODO
-        </para>
+        <listitem>
+          <para>
+            TODO
+          </para>
+        </listitem>
       </varlistentry>
       <varlistentry>
         <term>Gradient smoothness</term>
-        <para>
-          TODO
-        </para>
+        <listitem>
+          <para>
+            TODO
+          </para>
+        </listitem>
       </varlistentry>
       <varlistentry>
         <term>Spatial regularization</term>
-        <para>
-          TODO
-        </para>
+        <listitem>
+          <para>
+            TODO
+          </para>
+        </listitem>
       </varlistentry>
       <varlistentry>
         <term>Superpixels color</term>
-        <para>
-          TODO
-        </para>
+        <listitem>
+          <para>
+            TODO
+          </para>
+        </listitem>
       </varlistentry>
     </variablelist>
   </sect3>
diff --git a/src/toolbox/selection/free.xml b/src/toolbox/selection/free.xml
index 736d89120..da03d9448 100644
--- a/src/toolbox/selection/free.xml
+++ b/src/toolbox/selection/free.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                        "http://www.docbook.org/xml/4.3/docbookx.dtd";>
 <!-- section history:
-  
+  2019-02-03 j.h: rewrite explanations
 -->
 <sect2 id="gimp-tool-free-select" xmlns:xi="http://www.w3.org/2001/XInclude";>
   <title>Free Selection (Lasso)</title>
@@ -30,24 +30,63 @@
       </imageobject>
     </mediaobject>
   </figure>
-
+  
   <para>
     The Free Selection tool, or Lasso, lets you create a selection by drawing
-    it free-hand with the pointer, while holding down the left mouse button
-    (or, for a stylus, pressing it against the tablet). When you release the
-    mouse button, the selection is closed by connecting the current pointer
-    location to the start location with a straight line. You can go outside
-    the edge of the image display and come back in if you want to. The Lasso
-    is often a good tool to use for <quote>roughing in</quote> a selection;
-    it is not so  good for precise definition. Experienced users find that
-    it  is often convenient to begin with the lasso tool, but then switch to
-    <link linkend="gimp-qmask">QuickMask</link> mode for detail work.
+    it with the pointer.
+  </para>
+  <para>
+    Since GIMP-2.6, you can use it in two ways. First create 
+    the <emphasis>starting point</emphasis> clicking on your image. Then,
+    <itemizedlist>
+      <listitem>
+        <para>
+          Maintaining the mouse button pressed (i.e click-and-drag), drag to 
+          draw a free hand selection. When <emphasis>end point</emphasis> comes 
+          superimposed on the starting point, release the mouse button to 
+            <emphasis>close the selection</emphasis>.
+        </para>
+        <para>
+          If you click on the end point, it turns accompanied by a moving cross. 
+          Then, dragging enlarges the shape.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Or release the mouse button and drag to draw a polygonal selection. 
+          When the <emphasis>end point</emphasis> comes superimposed on the 
+          starting point, click to <emphasis>close the selection</emphasis>.
+        </para>
+        <para>
+          Press the <keycap>Ctrl</keycap> keyboard key and click on the end 
+          point: moving the mouse pointer forces moving angles to 15°; so, you 
+          can draw horizontal or vertical lines easily.
+        </para>
+      </listitem>
+    </itemizedlist>
+    In both cases, double clicking on the end point closes the selection with a 
+    straight line.
+  </para>
+  <para>
+    Press <keycap>Enter</keycap> or double click inside the shape to validate 
+    the selection.
+  </para>
+  <para>
+    Pressing and releasing the mouse pointer allows you to mix free hand 
+    <emphasis>segments</emphasis> and polygonal segments. You can go outside
+    the edge of the image display and come back in if you want to.
   </para>
   <para>
-    For information on selections and how
-    they are used in GIMP see
-    <link linkend="gimp-concepts-selection">Selections</link>.  For
-    information on features common to all selection tools see
+    The Lasso is often a good tool to use for <quote>roughing in</quote> a 
+    selection; it is not so  good for precise definition. Experienced users 
+    find that it  is often convenient to begin with the lasso tool, but then 
+    switch to <link linkend="gimp-qmask">QuickMask</link> mode for detail work.
+  </para>
+  
+  <para>
+    For information on selections and how they are used in GIMP see
+    <link linkend="gimp-concepts-selection">Selections</link>. For information 
+    on features common to all selection tools see
     <link linkend="gimp-tool-select">Selection Tools</link>.
   </para>
   <note>
@@ -57,19 +96,6 @@
     </para>
   </note>
 
-  <para>
-    A new possibility came up with GIMP-2.6: the polygonal selection.
-    Instead of click-and-dragging to draw a free hand selection, you can
-    click only. This creates an anchor point. Then moving the mouse pointer
-    draws a line with a new anchor point that you can move as long as you
-    don't click again (the mouse pointer comes with the moving cross).
-    Clicking again anchors this point and creates a segment. By pressing
-    the <keycap>Ctrl</keycap> keyboard key while moving the mouse pointer
-    contrains moving angles to 15°.
-  </para>
-  <para>
-    So, you can mix free hand segments and polygonal segments.
-  </para>
   <figure>
     <title>Mixing free hand segments and polygonal segments</title>
     <mediaobject>