New attempt (vignette.xml)

src/filters/light-and-shadow/vignette.xml

@@ -2,6 +2,7 @@
 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                        "http://www.docbook.org/xml/4.3/docbookx.dtd">
 <!-- section history:
+  2020-07-17 j.h: update to 2.10.20
   2019-01-06 j.h: create
 -->
 <sect2 xmlns:xi="http://www.w3.org/2001/XInclude" id="gimp-filter-vignette">
@@ -24,6 +25,7 @@
       draw attention to the center of the image. <quote>Vignette</quote> can 
       produce this effect.
     </para>
+        
     <figure>
       <title>Original images used for examples</title>
       <mediaobject>
@@ -51,6 +53,56 @@ format="JPG"/>
         </caption>
       </mediaobject>
     </figure>
+    <para id="on-canvas-controls">
+      GIMP-2.10.20 comes with on-canvas controls (default): two limits with 
+      white handles that turn to orange, and become active, when mouse pointer 
+      hovers over them. The black (default) area is the 
+      <emphasis>vignette</emphasis>. The <emphasis>outer limit</emphasis> is 
+      the limit of the vignette. The <emphasis>inner limit</emphasis> is the 
+      limit of the <emphasis>soft area</emphasis>, the unchanged area. Between 
+      the outer and the inner limits is the <emphasis>fade area</emphasis>, 
+      where the vignette is fading progressively, with a dotted line 
+      that is the <emphasis>midpoint line</emphasis>.
+      <mediaobject>
+        <imageobject>
+          <imagedata 
+fileref="images/filters/examples/light-and-shadow/vignette-ex-oncanvas.jpg" 
+format="JPG"/>
+        </imageobject>
+        <caption>
+          <para>
+            Vignette with default options and on-canvas controls
+          </para>
+        </caption>
+      </mediaobject>
+    </para>
+    <para>
+      Click-and-drag action is different on lines and on handles:
+      <itemizedlist>
+        <listitem>
+          <para>
+            Click-and-drag a limit line to move the limit and the midpoint 
+            (Radius and Softness).
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Click-and-drag a handle to move both limits (Radius and Squeeze).
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Click-and-drag the midpoint line to move it.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            In the three cases, pressing <keycap>Shift</keycap> only changes 
+            Radius.
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
   </sect3>
   
   <sect3>
@@ -78,9 +130,11 @@ fileref="images/filters/light-and-shadow/vignette-dialog.png" format="PNG"/>
     </figure>
     <variablelist>
       <varlistentry>
-        <term>Presets, Preview, Split view</term>
+        <term>Presets, Preview, Split view, Blending options</term>
         <listitem>
-          <xi:include href="../about-common-features.xml"/>
+          <para>
+            <xi:include href="../about-common-features.xml"/>
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -96,6 +150,12 @@ fileref="images/filters/light-and-shadow/vignette-dialog.png" format="PNG"/>
             <listitem>
               <para>Diamond</para>
             </listitem>
+            <listitem>
+              <para>
+                Horizontal, Vertical: limits and line are horizontal or 
+                vertical.
+              </para>
+            </listitem>
           </itemizedlist>
           <para>
             The shape of the vignette (ellipse or circle for example) depends on 
@@ -107,7 +167,8 @@ fileref="images/filters/light-and-shadow/vignette-dialog.png" format="PNG"/>
         <term>Radius</term>
         <listitem>
           <para>
-            How far out vignetting goes as part of half image diagonal.
+            Vignette size: how far out vignetting goes as part of half image 
+            diagonal.
           </para>
           <mediaobject>
             <imageobject>
@@ -127,7 +188,7 @@ format="JPG"/>
         <term>Softness</term>
         <listitem>
           <para>
-            TODO.
+            Soft (unchanged) area size.
           </para>
           <mediaobject>
             <imageobject>
@@ -149,7 +210,7 @@ format="JPG"/>
           <para>
             Falloff linearity controls the curve of the falloff from the center 
             to periphery: set how fast is brightness reduced towards edges 
-            of the vignette.
+            of the vignette(fading area size).
           </para>
           <mediaobject>
             <imageobject>
@@ -234,14 +295,20 @@ format="JPG"/>
           <para>
             Rotation of the vignette. The vignette keeps its shape.
           </para>
+          <para>
+            You can also click-and-drag outside the outer limit to rotate the 
+            vignette.
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term>Use the selection as input, Use the entire layer as input</term>
+        <term>On-canvas controls</term>
         <listitem>
-          <xi:include href="../about-common-features.xml"/>
+          <para>
+            Uncheck this option to remove on-canvas controls.
+          </para>
         </listitem>
       </varlistentry>
     </variablelist>
   </sect3>
-</sect2>
\ No newline at end of file
+</sect2>