[gimp-help] Add Lock brush to view in paint tools common features

[Julien Hardlin <jhardlin src gnome org>]

commit d93fd51cc7d17ef5a05fd30d97fe506604e3c52b
Author: Julien Hardelin <jhardlin orange fr>
Date:   Fri Sep 28 16:11:27 2018 +0200

    Add Lock brush to view  in paint tools common features

 images/C/tool-options/lockbrush-orig.png           | Bin 0 -> 67350 bytes
 images/C/tool-options/lockbrush-rotation-lock.png  | Bin 0 -> 20177 bytes
 .../C/tool-options/lockbrush-rotation-nolock.png   | Bin 0 -> 20156 bytes
 images/C/tool-options/lockbrush-zoom200-lock.png   | Bin 0 -> 133516 bytes
 images/C/tool-options/lockbrush-zoom200-nolock.png | Bin 0 -> 128630 bytes
 src/toolbox/paint/common-features.xml              | 121 ++++++++++++++++++---
 6 files changed, 104 insertions(+), 17 deletions(-)
---
diff --git a/images/C/tool-options/lockbrush-orig.png b/images/C/tool-options/lockbrush-orig.png
new file mode 100644
index 000000000..aeedc2aa6
Binary files /dev/null and b/images/C/tool-options/lockbrush-orig.png differ
diff --git a/images/C/tool-options/lockbrush-rotation-lock.png 
b/images/C/tool-options/lockbrush-rotation-lock.png
new file mode 100644
index 000000000..f0ee21df3
Binary files /dev/null and b/images/C/tool-options/lockbrush-rotation-lock.png differ
diff --git a/images/C/tool-options/lockbrush-rotation-nolock.png 
b/images/C/tool-options/lockbrush-rotation-nolock.png
new file mode 100644
index 000000000..7b3fd82bf
Binary files /dev/null and b/images/C/tool-options/lockbrush-rotation-nolock.png differ
diff --git a/images/C/tool-options/lockbrush-zoom200-lock.png 
b/images/C/tool-options/lockbrush-zoom200-lock.png
new file mode 100644
index 000000000..04a03f619
Binary files /dev/null and b/images/C/tool-options/lockbrush-zoom200-lock.png differ
diff --git a/images/C/tool-options/lockbrush-zoom200-nolock.png 
b/images/C/tool-options/lockbrush-zoom200-nolock.png
new file mode 100644
index 000000000..cebac9c25
Binary files /dev/null and b/images/C/tool-options/lockbrush-zoom200-nolock.png differ
diff --git a/src/toolbox/paint/common-features.xml b/src/toolbox/paint/common-features.xml
index fa80c5d1d..36ebf91b5 100644
--- a/src/toolbox/paint/common-features.xml
+++ b/src/toolbox/paint/common-features.xml
@@ -2,11 +2,12 @@
 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                        "http://www.docbook.org/xml/4.3/docbookx.dtd";>
 <!-- section history:
+  2018-09-28 j.h: documented Lock brush to view
   2012-11-16 j.h: documented Smooth Stroke
   2012-10-15 Kolbjoern: documented Dynamics
-  2007-10-29 j.h: documented Scale, Jitter en;fr
+  2007-10-29 j.h: documented Scale, Jitter
 -->
-<sect2 id="gimp-tool-brush">
+<sect2 xmlns:xi="http://www.w3.org/2001/XInclude"; id="gimp-tool-brush">
   <title>Common Features</title>
 
   <para>
@@ -380,7 +381,7 @@
             full pressure and then ramps down again to no pressure. Velocity 
             starts from zero and ramps up to full speed by the end of the  
             stroke.
-          </para>          
+          </para>
         </listitem>
       </varlistentry>
 
@@ -390,7 +391,7 @@
           <para>
             These options are described in 
             <link linkend="gimp-tool-dynamic-options">Dynamics Options</link>
-          </para>        
+          </para>
         </listitem>
       </varlistentry>
 
@@ -464,24 +465,110 @@
       </varlistentry>
       
       <varlistentry>
-        <term>Lock brush size to zoom</term>
+        <term>Lock brush size to view</term>
         <listitem>
           <para>
-            TODO
+            When you are working on an image that is bigger (in pixels) than 
+            your screen, you have to zoom in and out a lot. This option 
+            allows a very natural "iterative refinement" process with no need to 
+            repeatedly ask the application to change brush size as you go 
+            between the broad strokes and the detailing.
           </para>
-        </listitem>
-      </varlistentry>
-      
-      <varlistentry>
-        <term>Hard edge</term>
-        <listitem>
           <para>
-            TODO
+            If the brush size is relative to the canvas (option unchecked), 
+            zooming in makes the brush zoomed also and it appears larger (takes 
+            up more pixels on the screen). If you're working with a 300 pixels 
+            radius brush and you zoom in from 12% to 100%, the brush is now 
+            half the size of your screen! So you have to shrink the brush back 
+            down.
           </para>
+          <para>
+            If the brush size is relative to the screen (option checked), then 
+            when you zoom in, the size of the displayed brush doesn't change, it 
+            looks smaller and so you can work on tiny details.
+          </para>
+          <figure>
+            <title>Lock brush example</title>
+            <mediaobject>
+              <imageobject>
+                <imagedata format="PNG"
+                  fileref="images/tool-options/lockbrush-orig.png"/>
+              </imageobject>
+              <caption>
+                <para>
+                  This image is the screenshot of a small part of a TIFF image 
+                  bigger than my screen. Here, GIMP displays this TIFF image at 
+                  50% zoom, so the whole image is visible. The option is not 
+                  checked, brush size in toolbox is 100 pixels high.
+                </para>
+              </caption>
+            </mediaobject>
+            <mediaobject>
+              <imageobject>
+                <imagedata format="PNG"
+                  fileref="images/tool-options/lockbrush-zoom200-nolock.png"/>
+              </imageobject>
+              <caption>
+                <para>
+                  Screenshot: zoom 200. The option is not checked. We 
+                  paint with pencil and the pepper brush that is 100 pixels 
+                  high in toolbox: displayed brush stroke is 200 pixels high.
+                </para>
+              </caption>
+            </mediaobject>
+            <mediaobject>
+              <imageobject>
+                <imagedata format="PNG"
+                  fileref="images/tool-options/lockbrush-zoom200-lock.png"/>
+              </imageobject>
+              <caption>
+                <para>
+                  Screenshot: zoom 200. The option is checked. We 
+                  paint with pencil and the pepper brush that is 100 pixels 
+                  high in toolbox: displayed brush stroke is 100 pixels high.
+                </para>
+              </caption>
+            </mediaobject>
+          </figure>
+          <para>
+            "Lock brush to view" can also be used to lock brush to view 
+            rotation:
+          </para>
+          <figure>
+            <title>Lock brush to view rotation example</title>
+            <mediaobject>
+              <imageobject>
+                <imagedata format="PNG"
+                  fileref="images/tool-options/lockbrush-rotation-nolock.png"/>
+              </imageobject>
+              <caption>
+                <para>
+                  Screenshot. Here, the option is unchecked and we use 
+                  <menuchoice>
+                    <guimenu>View</guimenu>
+                    <guisubmenu>Flip and Rotate</guisubmenu>
+                    <guimenuitem>>Rotate 15° clockwise</guimenuitem>
+                  </menuchoice>: brush stroke is rotated.
+                </para>
+              </caption>
+            </mediaobject>
+            <mediaobject>
+              <imageobject>
+                <imagedata format="PNG"
+                  fileref="images/tool-options/lockbrush-rotation-lock.png"/>
+              </imageobject>
+              <caption>
+                <para>
+                  Same thing but the option is checked: the brush is locked to 
+                  the original, not rotated view and brush stoke is not rotated.
+                </para>
+              </caption>
+            </mediaobject>
+          </figure>
         </listitem>
       </varlistentry>
-
-      <varlistentry>
+      
+     <varlistentry>
         <term>Incremental</term>
         <listitem>
           <para>
@@ -614,7 +701,7 @@
           </para>
           <para>
             The next image (below) has two layers. The upper layer is active.
-            Three brushtrokes with pencil, red color at 100%, 50%, 25%: only
+            Three brush strokes with pencil, red color at 100%, 50%, 25%: only
             transparent or semi-transparent pixels of the layer are painted.
           </para>
           <figure>
@@ -680,7 +767,7 @@
           </para>
           <para>
             This image below has only one layer, the background layer.
-            Background color is sky blue. Three brushtrokes with
+            Background color is sky blue. Three brush strokes with
             pencil:
           </para>
           <orderedlist>