update docs

diff --git a/CHANGES.md b/CHANGES.md
index 18f6d44708c370df9e59b2df81ac291326288fbc..9cbb82be313cff077b5eb44e128a44408d296f16 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,11 @@
       # perltidy -drc:
             ignoreSpec( $file, "file", \%spec, \%Rspec );
 
+    - Fixed a minor inconsistency in html colors when -html is used.
+      Previously, a '->' at the end of a line got a black color by default,
+      but a '->' within a line got the color of the following identifier.
+      Now all pointers get the same color, which is black by default.
+
 ## 2022 06 13
 
     - No significant bugs have been found since the last release but users

diff --git a/dev-bin/RandomTesting.md b/dev-bin/RandomTesting.md
index b8a527638326b6c563078d4cacf0653c4341760f..157783b86c534eec1a2d5ac896d3195f5cb0c43b 100644 (file)
--- a/dev-bin/RandomTesting.md
+++ b/dev-bin/RandomTesting.md
@@ -1,19 +1,42 @@
 # Running Random Tests with Perltidy
 
-The basic idea is to try to cause perltidy to fail in some way by running it on
-a large number of random input parameters and files.  The runs which do this
-work can run for many hours, processing hundreds of test files, each with
-perhaps hundreds of parameter combinations.  The results can be checked at any
-time, and the scripts are written so that they can stop and restart any time.
-That's okay, computer time is cheap.  The hard part will be at the end, sifting
-through the results.
-
-When this type of testing was begun, several dozen problems were quickly
-identified and fixed.  The most common problem was that an uninitialized
-variable was referenced in some way.  It has been some time since a new problem
-was detected with these scripts, but it is important to run these
-tests periodically, and always before a release, because new coding and new
-parameters may introduce bugs.
+The tests which ship with perltidy check that its basic functionality is
+correct.  Perltidy has well over 100 input parameters, and most of them are
+checked in a simple way with these tests.  But when we consider that the
+parameters do not each operate independently but rather interact with each
+other, these tests barely "scratch the surface" in testing perltidy. It would
+require an impossible number of tests to really do an in-depth check for
+problems.  To illustrate, suppose we had just 100 input parameters and they
+were simple binary switches, we would need 2^100, or about 10^30, tests to test
+all possible combinations. But many of the flags can take more than 2 settings,
+so the number of combinations in far greater.  For example, the line length
+parameter takes any integer as value.  And the problem becomes even more
+complex when we consider that problems among interacting parameters may only
+occur on some particular sequence of input text.
+
+What to do?  Several strategies have been developed to handle this problem. One
+of these which has always been used is to check all source code changes
+on a very large body of perl code with a variety of parameter settings.  This requires
+several cpu hours of runs for each coding change.
+
+Another approach, described here, is random testing.  The basic idea is
+to try to cause perltidy to fail in some way by running it on a large number of
+random input parameters and files.  The runs which do this work can run for
+many hours, processing hundreds of test files, each with many thousands of
+random parameter combinations.  The results can be checked at any time, and the
+scripts are written so that they can stop and restart any time.  That's okay,
+computer time is cheap.
+
+This type of testing has been extremely helpful in making perltidy more robust.
+Over 1300 issues have been identified with this method so far and have been
+corrected.  All of these are extremely rare edge cases that would have been
+difficult to find by any other method.  Perltidy has become very robust as a
+result of this work, and the mean time for the discovery of a new convergence
+issue is now about 50 cpu hours.
+
+Another strategy which is employed at the same time is to turn on the
+``DEVEL_MODE`` flags in perltidy which cause it to do numerous self-checks as
+it runs.  These slow perltidy down, so they are only turned on during testing.
 
 There are currently a set of three scripts for this work.
 
@@ -27,9 +50,8 @@ personal bin directory.
 
 ## Prepare a temporary directory
 
-First collect a large number (say 50 or more) of arbitrary perl scripts in a
-single directory.  You may also include other arbitrary files, such as
-text or html files.
+First collect a large number of arbitrary perl scripts in a single directory.
+You may also include other arbitrary files, such as text or html files.
 
 Then create a temporary sub directory and enter it, say
 

diff --git a/docs/eos_flag.md b/docs/eos_flag.md
index 11bda6d67df9fb1d7d16aa2007e9d767a022ed1b..1dca74e0bc869e7b8f5f4c5ee67ca9c60bae4188 100644 (file)
--- a/docs/eos_flag.md
+++ b/docs/eos_flag.md
@@ -32,15 +32,15 @@ source and decoded it from a utf8 but did not re-encode it before storing it in
 the output string.  So the source string was in a different storage mode than
 the output string, and a direct comparison was not meaningful.
 
-This problem is an unintentional result of the historical evolution of perltidy and needs to be fixed.
+This problem is an unintentional result of the historical evolution of perltidy.
 
 The same problem occurs if the destination is an array rather than a string,
 so for simplicity we can limit this discussion to string destinations, which
 are more common.
 
-## How will the problem be fixed?
+## How has the problem been fixed?
 
-A fix is being phased in over a couple of steps. The first step was to
+A fix was phased in over a couple of steps. The first step was to
 introduce a new flag in in version 20220217.  The new flag is
 **--encode-output-strings**, or **-eos**.  When this is set, perltidy will fix
 the specific problem mentioned above by doing an encoding before returning.
@@ -60,9 +60,9 @@ To illustrate using this flag in the above example, we could write
     );
 ```
 
-With this modification we can make a meaningful direct comparison of `$source` and `$output`. The test on `$VERSION` allows this to work with older versions of perltidy (which would not recognize the flag -eos).  An update such as the above can be made right now to facilitate a smooth transition to the new default.
+With this modification we can make a meaningful direct comparison of `$source` and `$output`. The test on `$VERSION` allows this to work with older versions of perltidy (which would not recognize the flag -eos).
 
-In the second step, possibly later in 2022, the new **-eos** flag will become the default.
+In the second step, introduced in version 20220613, the new **-eos** flag became the default.
 
 ## What can go wrong?
 
@@ -115,17 +115,15 @@ A related problem is if an update of Perl::Tidy is made without also updating
 a corrected version of a module such as the above.  To help reduce the chance
 that this will occur the Change Log for perltidy will contain a warning to be
 alert for the double encoding problem, and how to reset the default if
-necessary.  This is also the reason for waiting some time before the second step is made.
+necessary.  This is also the reason for waiting some time before the second step was made.
 
-If double encoding does appear to be occuring after the default change for some program which calls Perl::Tidy, then a quick emergency fix can be made by the program user by setting **-neos** to revert to the old default.  A better fix can eventually be made by the program author by removing the second encoding using a technique such as illustrated above.
+If double encoding does appear to be occuring with the change in the default for some program which calls Perl::Tidy, then a quick emergency fix can be made by the program user by setting **-neos** to revert to the old default.  A better fix can eventually be made by the program author by removing the second encoding using a technique such as illustrated above.
 
 ## Summary
 
 A new flag, **-eos**, has been added to cause Perl::Tidy to behave better as a
-filter when called from other Perl scripts.  This flag will eventually become
-the default setting.  Programs which use Perl::Tidy as a
-filter can be tested right now with the new **-eos** flag to be sure that double
-encoding is not possible when the default is changed.
+filter when called from other Perl scripts.  This flag is the default setting
+in the current release.
 
 ## Reference