Docs: update plotgitsch hands on guide

docs/plotgitsch_usersguide.adoc

@@ -48,9 +48,9 @@ This is a checkout of what is usually followed under git in kicad projects. For
 
 == Internal Diff
 
-Although `plotgitsch` is invoked by default to run an external image diff tool, we will focus on using the internal diff feature by using the `-i` option. This feature tries to compute the visual differences between internal list of drawing primitives (lines, texts, arcs…) of the schematics drawings and keeps the difference at the level of https://en.wikipedia.org/wiki/Vector_graphics[vector graphics], which allows any zooming level.
+Although `plotgitsch` is invoked by default to run an external image diff tool, we will focus on using the internal diff feature by using the `-i` option. This feature tries to compute the visual differences between lists of drawing primitives (lines, texts, arcs…) of the schematics drawings and keeps the difference at the level of https://en.wikipedia.org/wiki/Vector_graphics[vector graphics], which allows any zooming level.
 
-This way of doing has a down side of showing diffs where an element has been deleted and an identical one has been put at the same place. That's why it is important to change your schematic by moving things around instead of deleting everything.
+The primitives are reordered internally, so that the diffing algorithm can cope with great reworks of the schematics but still find the differences at the shape level.
 
 In order to visualize the vector output of the difference, you'll need an application able to display SVG pictures. Your default web browser should be able to handle these files. Let's try for instance with firefox:
 
@@ -71,13 +71,13 @@ This is the display of changes that were introduced in your present working copy
 
 For the simplicity of this guide, all the revisions of this playground repo have been tagged so that you can easily type them in.
 
-`plotgitsch` handles revision specifiers just like git (behind the scene, it uses git). Please have a look at https://git-scm.com/docs/gitrevisions[git revisions] for all the kinds of commit references.
+`plotgitsch` handles revision specifiers just like git (behind the scene, it uses git). Please have a look at https://git-scm.com/docs/gitrevisions[git revisions] for all the kinds of commit reference specifiers.
 
 Revisions to be compared can be specified in three forms: with two, one or no revisions.
 
- 1. `plotgitsch` alone, which performs the comparison between the working copy and `HEAD` (the tip of the branch you have checked out). This is by far the most used one. Very helpful for checking what's changed before committing.
- 2. `plotgitsch <rev>` performs the comparison between the working copy and the given revision. You can quickly spot what changed since the last tagged prototype.
- 3. `plotgitsch <rev1> <rev2>`, with `rev1` and `rev2` being two references to commits (tag, branch or any commitish form). The changes in  schematic sheets from `rev1` to `rev2` are displayed.
+ 1. `plotgitsch` alone, performs the comparison between the working copy and `HEAD` (the tip of the branch you have checked out). This is by far the most used one. Very helpful for verifying what's changed before committing.
+ 2. `plotgitsch <rev>` performs the comparison between the working copy and the given revision _rev_ . You can quickly spot what changed since the last tagged prototype.
+ 3. `plotgitsch <rev1> <rev2>`, with _rev1_ and _rev2_ being two references to commits (tag, branch or any commitish form). The changes in schematic sheets from _rev1_ to _rev2_ are displayed.
 
 For instance, let's check the changes between two tagged revisions:
 
@@ -88,6 +88,9 @@ $ plotgitsch -ifirefox v0.0.3 v0.0.4
 
 image::LED_swap.png[]
 
+
+TIP: You can also diff plain directories, without any reference to git, by using the scheme `dir:<directory>` for a side of diff: `plotgitsch dir:<dir1> dir:<dir2>` will perform the schematic diff between directories _dir1_ and _dir2_.
+
 == Changing Colors
 
 By default, the background is white, the unmodified part of the drawing is black, the added parts are green and the removed ones are red. These colors can be changed with the `-c` option. Say we'd rather have the background in black (RGB hex code 000000), the unchanged parts in white (RGB hex: FFFFFF), the added lines in clear blue (RGB hex: 008FFF) and keep the removed in red (RGB hex: FF0000), we need to issue the following command:
@@ -147,6 +150,8 @@ Another option is to use environment variables to customize the behavior of `plo
    This variable makes `plotgitsch` use the internal differ and its value is the command of the viewer.
 `PLOTGITSCH_COLORS`::
    This variable is the value passed to the `--colors` option.
+`PLOTGITSCH_CHANGE_COLOR`::
+   This variable activate change zone highlighting with the specified color in hex format #rrggbb
 
 Set and export these variables in your `$HOME/.bashrc` or in you `$HOME/.profilerc`, like this:
 
@@ -168,5 +173,8 @@ There are a few last options:
 `--version`::
   Show the version string.
 
+`-z#_<RRGGBB>_`, `--zone=#_<RRGGBB>_`::
+  Highlight the change zones in the diff output with specified colors.
+
 `--help`::
   Show a very helpful manual page.

docs/plotgitsch_usersguide.html

@@ -542,10 +542,10 @@ <h2 id="_set_up">Set Up</h2>
 <h2 id="_internal_diff">Internal Diff</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>Although <code>plotgitsch</code> is invoked by default to run an external image diff tool, we will focus on using the internal diff feature by using the <code>-i</code> option. This feature tries to compute the visual differences between internal list of drawing primitives (lines, texts, arcs…) of the schematics drawings and keeps the difference at the level of <a href="https://en.wikipedia.org/wiki/Vector_graphics">vector graphics</a>, which allows any zooming level.</p>
+<p>Although <code>plotgitsch</code> is invoked by default to run an external image diff tool, we will focus on using the internal diff feature by using the <code>-i</code> option. This feature tries to compute the visual differences between lists of drawing primitives (lines, texts, arcs…) of the schematics drawings and keeps the difference at the level of <a href="https://en.wikipedia.org/wiki/Vector_graphics">vector graphics</a>, which allows any zooming level.</p>
 </div>
 <div class="paragraph">
-<p>This way of doing has a down side of showing diffs where an element has been deleted and an identical one has been put at the same place. That&#8217;s why it is important to change your schematic by moving things around instead of deleting everything.</p>
+<p>The primitives are reordered internally, so that the diffing algorithm can cope with great reworks of the schematics but still find the differences at the shape level.</p>
 </div>
 <div class="paragraph">
 <p>In order to visualize the vector output of the difference, you&#8217;ll need an application able to display SVG pictures. Your default web browser should be able to handle these files. Let&#8217;s try for instance with firefox:</p>
@@ -578,21 +578,21 @@ <h2 id="_specifying_revisions_to_compare">Specifying Revisions to compare</h2>
 <p>For the simplicity of this guide, all the revisions of this playground repo have been tagged so that you can easily type them in.</p>
 </div>
 <div class="paragraph">
-<p><code>plotgitsch</code> handles revision specifiers just like git (behind the scene, it uses git). Please have a look at <a href="https://git-scm.com/docs/gitrevisions">git revisions</a> for all the kinds of commit references.</p>
+<p><code>plotgitsch</code> handles revision specifiers just like git (behind the scene, it uses git). Please have a look at <a href="https://git-scm.com/docs/gitrevisions">git revisions</a> for all the kinds of commit reference specifiers.</p>
 </div>
 <div class="paragraph">
 <p>Revisions to be compared can be specified in three forms: with two, one or no revisions.</p>
 </div>
 <div class="olist arabic">
 <ol class="arabic">
 <li>
-<p><code>plotgitsch</code> alone, which performs the comparison between the working copy and <code>HEAD</code> (the tip of the branch you have checked out). This is by far the most used one. Very helpful for checking what&#8217;s changed before committing.</p>
+<p><code>plotgitsch</code> alone, performs the comparison between the working copy and <code>HEAD</code> (the tip of the branch you have checked out). This is by far the most used one. Very helpful for verifying what&#8217;s changed before committing.</p>
 </li>
 <li>
-<p><code>plotgitsch &lt;rev&gt;</code> performs the comparison between the working copy and the given revision. You can quickly spot what changed since the last tagged prototype.</p>
+<p><code>plotgitsch &lt;rev&gt;</code> performs the comparison between the working copy and the given revision <em>rev</em> . You can quickly spot what changed since the last tagged prototype.</p>
 </li>
 <li>
-<p><code>plotgitsch &lt;rev1&gt; &lt;rev2&gt;</code>, with <code>rev1</code> and <code>rev2</code> being two references to commits (tag, branch or any commitish form). The changes in  schematic sheets from <code>rev1</code> to <code>rev2</code> are displayed.</p>
+<p><code>plotgitsch &lt;rev1&gt; &lt;rev2&gt;</code>, with <em>rev1</em> and <em>rev2</em> being two references to commits (tag, branch or any commitish form). The changes in schematic sheets from <em>rev1</em> to <em>rev2</em> are displayed.</p>
 </li>
 </ol>
 </div>
@@ -609,6 +609,18 @@ <h2 id="_specifying_revisions_to_compare">Specifying Revisions to compare</h2>
 <img src="LED_swap.png" alt="LED swap">
 </div>
 </div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+You can also diff plain directories, without any reference to git, by using the scheme <code>dir:&lt;directory&gt;</code> for a side of diff: <code>plotgitsch dir:&lt;dir1&gt; dir:&lt;dir2&gt;</code> will perform the schematic diff between directories <em>dir1</em> and <em>dir2</em>.
+</td>
+</tr>
+</table>
+</div>
 </div>
 </div>
 <div class="sect1">
@@ -712,6 +724,10 @@ <h2 id="_setting_default_options">Setting Default Options</h2>
 <dd>
 <p>This variable is the value passed to the <code>--colors</code> option.</p>
 </dd>
+<dt class="hdlist1"><code>PLOTGITSCH_CHANGE_COLOR</code></dt>
+<dd>
+<p>This variable activate change zone highlighting with the specified color in hex format #rrggbb</p>
+</dd>
 </dl>
 </div>
 <div class="paragraph">
@@ -744,6 +760,10 @@ <h2 id="_other_options">Other Options</h2>
 <dd>
 <p>Show the version string.</p>
 </dd>
+<dt class="hdlist1"><code>-z#<em>&lt;RRGGBB&gt;</em></code>, <code>--zone=#<em>&lt;RRGGBB&gt;</em></code></dt>
+<dd>
+<p>Highlight the change zones in the diff output with specified colors.</p>
+</dd>
 <dt class="hdlist1"><code>--help</code></dt>
 <dd>
 <p>Show a very helpful manual page.</p>
@@ -755,7 +775,7 @@ <h2 id="_other_options">Other Options</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-05-22 19:20:12 +0200
+Last updated 2021-01-03 14:36:08 +0100
 </div>
 </div>
 </body>