update docs

diff --git a/CHANGES.md b/CHANGES.md
index 383b704dcd9c3ee36b7529b0b565f9d17aeddb4a..ade00efb33f1531f0bbbc8f97beff58761d1c537 100644 (file)
--- 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 bc184552e28711827a3493d6d3a8d65afc75ca3a..6268d1f0d54a9163b1b4a57e1dd4da9ce9ac8842 100644 (file)
--- 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 57847dc18a035fc7c0a664b5353ab4ea52328548..1148de754be589f6e601e91d5c29ad6953fbba5a 100644 (file)
--- 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