From 9384ab8d8f1c1910f459deece9f4d9c4af29648d Mon Sep 17 00:00:00 2001
From: Steve Hancock <perltidy@users.sourceforge.net>
Date: Mon, 23 Nov 2020 12:51:52 -0800
Subject: [PATCH] update docs

---
 CHANGES.md          |  8 +++++---
 docs/BugLog.html    | 28 ++++++++++++++++++++++++++++
 docs/ChangeLog.html |  8 ++++++++
 3 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 383b704d..ade00efb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -66,9 +66,11 @@
 
     - A better test for convergence has been added. When iterations are requested,
       the new test will stop after the first pass if no changes in line break
-      locations are made.  Previously, at least two passes were required to verify
-      convergnece unless the output stream had the same checksum as the input stream.
-      Extensive testing has been made to verify the correctness of the new test.
+      locations are made.  Previously, file checksums were used and required at least two 
+      passes to verify convergence unless no formatting changes were made.  With the new test, 
+      only a single pass is needed when formatting changes are limited to adjustments of 
+      indentation and whitespace on the lines of code.  Extensive testing has been made to
+      verify the correctness of the new convergence test.
 
     - Line breaks are now automatically placed after 'use overload' to 
       improve formatting when there are numerous overloaded operators.  For
diff --git a/docs/BugLog.html b/docs/BugLog.html
index bc184552..6268d1f0 100644
--- a/docs/BugLog.html
+++ b/docs/BugLog.html
@@ -21,6 +21,34 @@
 
 <dl>
 
+<dt id="fix-to-prevent-conversion-of-a-block-comment-to-hanging-side-comment"><b>fix to prevent conversion of a block comment to hanging side comment</b></dt>
+<dd>
+
+<p>A rare situation was identified during testing in which a block comment could be converted to be a hanging side comment. For example:</p>
+
+<pre><code>    sub macro_get_names {    #
+    #
+    # %name = macro_get_names();  (key=macrohandle, value=macroname)
+    #
+        local (%name) = ();
+        ...
+    }</code></pre>
+
+<p>For the following specific contitions the block comment in line 2 could be converted into a hanging side comment, which is undesirable:</p>
+
+<pre><code>   1. It contains nothing except for a &#39;#&#39;
+   2. It follows a line with side comment
+   3. It has indentation level &gt; 0</code></pre>
+
+<p>An update was made to prevent this from happening. There are two cases, depending on the value of --maximum-consecutive-blank-lines, or -mbl. If this value is positive (the default) then a blank line is inserted above the block comment to prevent it from becoming a hanging side comment. If this -mbl is zero, then the comment is converted to be a static block comment which again prevents it from becoming a hanging side comment. This fix was made 23 Nov 2020.</p>
+
+</dd>
+<dt id="improved-convergence-test"><b>improved convergence test</b></dt>
+<dd>
+
+<p>A better test for convergence has been added. When iterations are requested, the new test will stop after the first pass if no changes in line break locations are made. Previously, at least two passes were required to verify convergnece unless the output stream had the same checksum as the input stream. Extensive testing has been made to verify the correctness of the new test. This update was made 23 Nov 2020, 29efb63.</p>
+
+</dd>
 <dt id="fixed-problem-with-vertical-alignments-involving-if-statements"><b>fixed problem with vertical alignments involving &#39;if&#39; statements</b></dt>
 <dd>
 
diff --git a/docs/ChangeLog.html b/docs/ChangeLog.html
index 57847dc1..1148de75 100644
--- a/docs/ChangeLog.html
+++ b/docs/ChangeLog.html
@@ -64,6 +64,14 @@
 - This version is about 20% faster than the previous version due to optimizations
   made with the help of Devel::NYTProf.
 
+- A better test for convergence has been added. When iterations are requested,
+  the new test will stop after the first pass if no changes in line break
+  locations are made.  Previously, file checksums were used and required at least two 
+  passes to verify convergence unless no formatting changes were made.  With the new test, 
+  only a single pass is needed when formatting changes are limited to adjustments of 
+  indentation and whitespace on the lines of code.  Extensive testing has been made to
+  verify the correctness of the new convergence test.
+
 - Line breaks are now automatically placed after 'use overload' to 
   improve formatting when there are numerous overloaded operators.  For
   example
-- 
2.39.5