X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=CHANGES.md;h=2a8a11ee06d6ade482b9b915f636e5a9a3a671b5;hb=f7b7d95d23cfcceb1d4adf1bf81d80029ae214e4;hp=83034a5e0e607f18899ec56338afe3e2f82ae816;hpb=7f27e55dce5925b2bbe8fcfca64f385e917a52be;p=perltidy.git

diff --git a/CHANGES.md b/CHANGES.md
index 83034a5..2a8a11e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,681 @@
 # Perltidy Change Log
 
+## 2022 06 13
+
+    - No significant bugs have been found since the last release but users
+      of programs which call the Perl::Tidy module should note the first
+      item below, which changes a default setting.  The main change to
+      existing formatting is the second item below, which adds vertical
+      alignment to 'use' statements.
+
+    - The flag --encode-output-strings, or -eos, is now set 'on' by default.
+      This has no effect on the use of the 'perltidy' binary script, but could
+      change the behavior of some programs which use the Perl::Tidy module on
+      files encoded in UTF-8.  If any problems are noticed, an emergency fix
+      can be made by reverting to the old default by setting -neos.  For
+      an explanation of why this change needs to be made see:
+
+      https://github.com/perltidy/perltidy/issues/92
+
+      https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md
+
+    - Added vertical alignment for qw quotes and empty parens in 'use'
+      statements (see issue #git 93).  This new alignment is 'on' by default
+      and will change formatting as shown below. If this is not wanted it can
+      be turned off with the parameter -vxl='q' (--valign-exclude-list='q').
+
+        # old default, or -vxl='q'
+        use Getopt::Long qw(GetOptions);
+        use Fcntl qw(O_RDONLY O_WRONLY O_EXCL O_CREAT);
+        use Symbol qw(gensym);
+        use Exporter ();
+
+        # new default
+        use Getopt::Long qw(GetOptions);
+        use Fcntl        qw(O_RDONLY O_WRONLY O_EXCL O_CREAT);
+        use Symbol       qw(gensym);
+        use Exporter     ();
+
+    - The parameter -kbb (--keep-break-before) now ignores a request to break
+      before an opening token, such as '('.  Likewise, -kba (--keep-break-after)
+      now ignores a request to break after a closing token, such as ')'. This
+      change was made to avoid a rare instability discovered in random testing.
+
+    - Previously, if a -dsc command was used to delete all side comments,
+      then any special side comments for controlling non-indenting braces got
+      deleted too. Now, these control side comments are retained when -dsc is
+      set unless a -nnib (--nonon-indenting-braces) flag is also set to
+      deactivate them.
+
+    - This version runs about 10 percent faster on large files than the previous
+      release due to optimizations made with the help of Devel::NYTProf.  Much
+      of the gain came from faster processing of blank tokens and comments.
+
+    - This version of perltidy was stress-tested for many cpu hours with
+      random input parameters. No failures to converge, internal fault checks,
+      undefined variable references or other irregularities were seen.
+
+## 2022 02 17
+
+    - A new flag, --encode-output-strings, or -eos, has been added to resolve
+      issue git #83. This issue involves the interface between Perl::Tidy and
+      calling programs, and Code::TidyAll (tidyall) in particular.  The problem
+      is that perltidy by default returns decoded character strings, but
+      tidyall expects encoded strings.  This flag provides a fix for that.
+
+      So, tidyall users who process encoded (utf8) files should update to this
+      version of Perl::Tidy and use -eos for tidyall.  For further info see:
+
+      https://github.com/houseabsolute/perl-code-tidyall/issues/84, and
+      https://github.com/perltidy/perltidy/issues/83
+
+      If there are other applications having utf8 problems at the interface
+      with Perl::Tidy, this flag probably may need to be set.
+
+    - The default value of the new flag, --encode-output-strings, -eos, is currently
+      -neos BUT THIS MAY CHANGE in a future release because the current
+      default is inconvenient.  So authors of programs which receive character
+      strings back from Perl::Tidy should set this flag, if necessary,
+      to avoid any problems when the default changes.  For more information see the
+      above links and the Perl::Tidy man pages for example coding.
+
+    - The possible values of the string 's' for the flag '--character-encoding=s'
+      have been limited to 'utf8' (or UTF-8), 'none', or 'guess'.  Previously an
+      arbitrary encoding could also be specified, but as a result of discussions
+      regarding git #83 it became clear that this could cause trouble
+      since the output encoding was still restricted to UTF-8. Users
+      who need to work in other encodings can write a short program calling
+      Perl::Tidy with pre- and post-processing to handle encoding/decoding.
+
+    - A new flag --break-after-labels=i, or -bal=i, was added for git #86.  This
+      controls line breaks after labels, to provide a uniform style, as follows:
+
+            -bal=0 follows the input line breaks [DEFAULT]
+            -bal=1 always break after a label
+            -bal=2 never break after a label
+
+      For example:
+
+          # perltidy -bal=1
+          INIT:
+            {
+                $xx = 1.234;
+            }
+
+          # perltidy -bal=2
+          INIT: {
+                $xx = 1.234;
+            }
+
+    - Fix issue git #82, an error handling something like ${bareword} in a
+      possible indirect object location. Perl allows this, now perltidy does too.
+
+    - The flags -kbb=s or --keep-old-breakpoints-before=s, and its counterpart
+      -kba=s or --keep-old-breakpoints-after=s have expanded functionality
+      for the container tokens: { [ ( } ] ).  The updated man pages have
+      details.
+
+    - Two new flags have been added to provide finer vertical alignment control,
+      --valign-exclusion-list=s (-vxl=s) and  --valign-inclusion-list=s (-vil=s).
+      This has been requested several times, most recently in git #79, and it
+      finally got done.  For example, -vil='=>' means just align on '=>'.
+
+    - A new flag -gal=s, --grep-alias-list=s, has been added as suggested in
+      git #77.  This allows code blocks passed to list operator functions to
+      be formatted in the same way as a code block passed to grep, map, or sort.
+      By default, the following list operators in List::Util are included:
+
+        all any first none notall reduce reductions
+
+      They can be changed with the flag -gaxl=s, -grep-alias-exclusion-list=s
+
+    - A new flag -xlp has been added which can be set to avoid most of the
+      limitations of the -lp flag regarding side comments, blank lines, and
+      code blocks.  See the man pages for more info. This fixes git #64 and git #74.
+      The older -lp flag still works.
+
+    - A new flag -lpil=s, --line-up-parentheses-inclusion-list=s, has been added
+      as an alternative to -lpxl=s, --line-up-parentheses-exclusion-list=s.
+      It supplies equivalent information but is much easier to describe and use.
+      It works for both the older -lp version and the newer -xlp.
+
+    - The coding for the older -lp flag has been updated to avoid some problems
+      and limitations.  The new coding allows the -lp indentation style to
+      mix smoothly with the standard indentation in a single file.  Some problems
+      where -lp and -xci flags were not working well together have been fixed, such
+      as happened in issue rt140025.  As a result of these updates some minor
+      changes in existing code using the -lp style may occur.
+
+    - This version of perltidy was stress-tested for many cpu hours with
+      random input parameters. No failures to converge, internal fault checks,
+      undefined variable references or other irregularities were seen.
+
+    - Numerous minor fixes have been made, mostly very rare formatting
+      instabilities found in random testing.
+
+## 2021 10 29
+
+    - No significant bugs have been found since the last release, but several
+      minor issues have been fixed.  Vertical alignment has been improved for
+      lists of call args which are not contained within parens (next item).
+
+    - Vertical alignment of function calls without parens has been improved with
+      the goal of making vertical alignment essentially the same with or
+      without parens around the call args.  Some examples:
+
+        # OLD
+        mkTextConfig $c, $x, $y, -anchor => 'se', $color;
+        mkTextConfig $c, $x + 30, $y, -anchor => 's',  $color;
+        mkTextConfig $c, $x + 60, $y, -anchor => 'sw', $color;
+        mkTextConfig $c, $x, $y + 30, -anchor => 'e', $color;
+
+        # NEW
+        mkTextConfig $c, $x,      $y,      -anchor => 'se', $color;
+        mkTextConfig $c, $x + 30, $y,      -anchor => 's',  $color;
+        mkTextConfig $c, $x + 60, $y,      -anchor => 'sw', $color;
+        mkTextConfig $c, $x,      $y + 30, -anchor => 'e',  $color;
+
+        # OLD
+        is id_2obj($id), undef, "unregistered object not retrieved";
+        is scalar keys %$ob_reg, 0, "object registry empty";
+        is register($obj), $obj, "object returned by register";
+        is scalar keys %$ob_reg, 1, "object registry nonempty";
+        is id_2obj($id), $obj, "registered object retrieved";
+
+        # NEW
+        is id_2obj($id),         undef, "unregistered object not retrieved";
+        is scalar keys %$ob_reg, 0,     "object registry empty";
+        is register($obj),       $obj,  "object returned by register";
+        is scalar keys %$ob_reg, 1,     "object registry nonempty";
+        is id_2obj($id),         $obj,  "registered object retrieved";
+
+      This will cause some changes in alignment, hopefully for the better,
+      particularly in test code which often uses numerous parenless function
+      calls with functions like 'ok', 'is', 'is_deeply', ....
+
+    - Two new parameters were added to control the block types to which the
+      -bl (--opening-brace-on-new-line) flag applies.  The new parameters are
+      -block-left-list=s, or -bll=s, and --block-left-exclusion-list=s,
+      or -blxl=s.  Previously the -bl flag was 'hardwired' to apply to
+      nearly all blocks. The default values of the new parameters
+      retain the the old default behavior but allow it to be changed.
+
+    - The default behavior of the -bli (-brace-left-and-indent) flag has changed
+      slightly.  Previously, if you set -bli, then the -bl flag would also
+      automatically be set.  Consequently, block types which were not included
+      in the default list for -bli would get -bl formatting.  This is no longer done,
+      and these two styles are now controlled independently.  The manual describes
+      the controls.  If you want to recover the exact previous default behavior of
+      the -bli then add the -bl flag.
+
+    - A partial fix was made for issue for git #74. The -lp formatting style was
+      being lost when a one-line anonymous sub was followed by a closing brace.
+
+    - Fixed issue git #73, in which the -nfpva flag was not working correctly.
+      Some unwanted vertical alignments of spaced function perens
+      were being made.
+
+    - Updated the man pages to clarify the flags -valign and -novalign
+      for turning vertical alignment on and off (issue git #72).
+      Added parameters -vc -vsc -vbc for separately turning off vertical
+      alignment of code, side comments and block comments.
+
+    - Fixed issue git #68, where a blank line following a closing code-skipping
+      comment, '#>>V', could be lost.
+
+    - This version runs 10 to 15 percent faster on large files than the
+      previous release due to optimizations made with the help of NYTProf.
+
+    - This version of perltidy was stress-tested for many cpu hours with
+      random input parameters. No instabilities,  internal fault checks,
+      undefined variable references or other irregularities were seen.
+
+    - Numerous minor fixes have been made, mostly very rare formatting instabilities
+      found in random testing. An effort has been made to minimize changes to
+      existing formatting that these fixes produce, but occasional changes
+      may occur. Many of these updates are listed at:
+
+           https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2021 07 17
+
+    - This release is being made mainly because of the next item, in which an
+      error message about an uninitialized value error message could be produced
+      in certain cases when format-skipping is used.  The error message was
+      annoying but harmless to formatting.
+
+    - Fixed an undefined variable message, see git #67. When a format skipping
+      comment '#<<' is placed before the first line of code in a script, a
+      message 'Use of uninitialized value $Ktoken_vars in numeric ...' can
+      occur.
+
+    - A warning will no longer be given if a script has an opening code-skipping
+      comment '#<<V' which is not terminated with a closing comment '#>>V'. This
+      makes code-skipping and format-skipping behave in a similar way: an
+      opening comment without a corresponding closing comment will cause
+      the rest of a file to be skipped.  If there is a question about which lines
+      are skipped, a .LOG file can be produced with the -g flag and it will have
+      this information.
+
+    - Removed the limit on -ci=n when -xci is set, reference: rt #136415.
+      This update removes a limit in the previous two versions in which the
+      value of -ci=n was limited to the value of -i=n when -xci was set.
+      This limit had been placed to avoid some formatting instabilities,
+      but recent coding improvements allow the limit to be removed.
+
+    - The -wn and -bbxx=n flags were not working together correctly. This has
+      been fixed.
+
+    - This version may produce occasional differences in formatting compared to
+      previous versions, mainly for lines which are near the specified line
+      length limit.  This is due to ongoing efforts to eliminate edge cases of
+      formatting instability.
+
+    - Numerous minor fixes have been made. A complete list is at:
+
+           https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2021 06 25
+
+    - This release adds several new requested parameters.  No significant bugs have
+      been found since the last release, but a number of minor problems have been
+      corrected.
+
+    - Added a new option '--code-skipping', requested in git #65, in which code
+      between comment lines '#<<V' and '#>>V' is passed verbatim to the output
+      stream without error checking.  It is simmilar to --format-skipping
+      but there is no error checking of the skipped code. This can be useful for
+      skipping past code which employs an extended syntax.
+
+    - Added a new option for closing paren placement, -vtc=3, requested in rt #136417.
+
+    - Added flag -atnl, --add-terminal-newline, to help issue git #58.
+      This flag tells perltidy to terminate the last line of the output stream
+      with a newline character, regardless of whether or not the input stream
+      was terminated with a newline character.  This is the default.
+      If this flag is negated, with -natnl, then perltidy will add a terminal
+      newline character to the the output stream only if the input
+      stream is terminated with a newline.
+
+    - Some nested structures formatted with the -lp indentation option may have
+      some changes in indentation.  This is due to updates which were made to
+      prevent formatting instability when line lengths are limited by the maximum line
+      length. Most scripts will not be affected. If this causes unwanted formatting
+      changes, try increasing the --maximum-line-length by a few characters.
+
+    - Numerous minor fixes have been made. A complete list is at:
+
+           https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2021 04 02
+
+    - This release fixes several non-critical bugs which have been found since the last
+    release.  An effort has been made to keep existing formatting unchanged.
+
+    - Fixed issue git #57 regarding uninitialized warning flag.
+
+    - Added experimental flag -lpxl=s requested in issue git #56 to provide some
+    control over which containers get -lp indentation.
+
+    - Fixed issue git #55 regarding lack of coordination of the --break-before-xxx
+    flags and the --line-up-parens flag.
+
+    - Fixed issue git #54 regarding irregular application of the --break-before-paren
+    and similar --break-before-xxx flags, in which lists without commas were not
+    being formatted according to these flags.
+
+    - Fixed issue git #53. A flag was added to turn off alignment of spaced function
+    parens.  If the --space-function-paren, -sfp flag is set, a side-effect is that the
+    spaced function parens may get vertically aligned.  This can be undesirable,
+    so a new parameter '--function-paren-vertical-alignment', or '-fpva', has been
+    added to turn this vertical alignment off. The default is '-fpva', so that
+    existing formatting is not changed.  Use '-nfpva' to turn off unwanted
+    vertical alignment.  To illustrate the possibilities:
+
+        # perltidy [default]
+        myfun( $aaa, $b, $cc );
+        mylongfun( $a, $b, $c );
+
+        # perltidy -sfp
+        myfun     ( $aaa, $b, $cc );
+        mylongfun ( $a, $b, $c );
+
+        # perltidy -sfp -nfpva
+        myfun ( $aaa, $b, $cc );
+        mylongfun ( $a, $b, $c );
+
+    - Fixed issue git #51, a closing qw bare paren was not being outdented when
+    the -nodelete-old-newlines flag was set.
+
+    - Fixed numerous edge cases involving unusual parameter combinations which
+      could cause alternating output states.  Most scripts will not be
+      changed by these fixes.
+
+    - A more complete list of updates is at
+
+           https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2021 01 11
+
+    - Fixed issue git #49, -se breaks warnings exit status behavior.
+    The exit status flag was not always being set when the -se flag was set.
+
+    - Some improvements have been made in the method for aligning side comments.
+    One of the problems that was fixed is that there was a tendency for side comment
+    placement to drift to the right in long scripts.  Programs with side comments
+    may have a few changes.
+
+    - Some improvements have been made in formatting qw quoted lists.  This
+    fixes issue git #51, in which closing qw pattern delimiters not always
+    following the settings specified by the --closing-token-indentation=n settings.
+    Now qw closing delimiters ')', '}' and ']' follow these flags, and the
+    delimiter '>' follows the flag for ')'.  Other qw pattern delimiters remain
+    indented as the are now.  This change will cause some small formatting changes
+    in some existing programs.
+
+    - Another change involving qw lists is that they get full indentation,
+    rather than just continuation indentation, if
+
+         (1) the closing delimiter is one of } ) ] > and is on a separate line,
+         (2) the opening delimiter  (i.e. 'qw{' ) is also on a separate line, and
+         (3) the -xci flag (--extended-continuation-indentation) is set.
+
+    This improves formatting when qw lists are contained in other lists. For example,
+
+            # OLD: perltidy
+            foreach $color (
+                qw(
+                AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
+                SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
+                ),
+                qw(
+                LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
+                SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
+                )
+              )
+
+            # NEW, perltidy -xci
+            foreach $color (
+                qw(
+                    AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
+                    SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
+                ),
+                qw(
+                    LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
+                    SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
+                )
+              )
+
+    - Some minor improvements have been made to the rules for formatting
+    some edge vertical alignment cases, usually involving two dissimilar lines.
+
+    - A more complete list of updates is at
+
+           https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2020 12 07
+
+    - Fixed issue git #47, incorrect welding of anonymous subs.
+      An incorrect weld format was being made when the --weld-nested-containers option
+      (-wn) was used in to format a function which returns a list of anonymous subs.
+      For example, the following snippet was incorrectly being welded.
+
+    $promises[$i]->then(
+        sub { $all->resolve(@_); () },
+        sub {
+            $results->[$i] = [@_];
+            $all->reject(@$results) if --$remaining <= 0;
+            return ();
+        }
+    );
+
+    This was due to an error introduced in v20201201 related to parsing sub
+    signatures.  Reformatting with the current version will fix the problem.
+
+## 2020 12 01
+
+    - This release is being made primarily to make available a several new formatting
+      parameters, in particular -xci, -kbb=s, -kba=s, and -wnxl=s. No significant
+      bugs have been found since the previous release, but numerous minor issues have
+      been found and fixed as listed below.
+
+    - This version is about 20% faster than the previous version due to optimizations
+      made with the help of Devel::NYTProf.
+
+    - Added flag -wnxl=s, --weld-nested-exclusion-list=s, to provide control which containers
+      are welded with the --weld-nested-containers parameter.  This is related to issue git #45.
+
+    - Merged pull request git #46 which fixes the docs regarding the -fse flag.
+
+    - Fixed issue git #45, -vtc=n flag was ignored when -wn was set.
+
+    - implement request RT #133649, delete-old-newlines selectively. Two parameters,
+
+      -kbb=s or --keep-old-breakpoints-before=s, and
+      -kba=s or --keep-old-breakpoints-after=s
+
+      were added to request that old breakpoints be kept before or after
+      selected token types.  For example, -kbb='=>' means that newlines before
+      fat commas should be kept.
+ 
+    - Fix git #44, fix exit status for assert-tidy/untidy.  The exit status was
+      always 0 for --assert-tidy if the user had turned off all error messages with
+      the -quiet flag.  This has been fixed.
+
+    - Add flag -maxfs=n, --maximum-file-size-mb=n.  This parameter is provided to
+      avoid causing system problems by accidentally attempting to format an 
+      extremely large data file. The default is n=10.  The command to increase 
+      the limit to 20 MB for example would be  -mfs=20.  This only applies to
+      files specified by filename on the command line.
+
+    - Skip formatting if there are too many indentation level errors.  This is 
+      controlled with -maxle=n, --maximum-level-errors=n.  This means that if 
+      the ending indentation differs from the starting indentation by more than
+      n levels, the file will be output verbatim. The default is n=1. 
+      To skip this check, set n=-1 or set n to a large number.
+
+    - A related new flag, --maximum-unexpected-errors=n, or -maxue=n, is available
+      but is off by default.
+
+    - Add flag -xci, --extended-continuation-indentation, regarding issue git #28
+      This flag causes continuation indentation to "extend" deeper into structures.
+      Since this is a fairly new flag, the default is -nxci to avoid disturbing 
+      existing formatting.  BUT you will probably see some improved formatting
+      in complex data structures by setting this flag if you currently use -ci=n 
+      and -i=n with the same value of 'n' (as is the case if you use -pbp, 
+      --perl-best-practices, where n=4).
+
+    - Fix issue git #42, clarify how --break-at-old-logical-breakpoints works.
+      The man page was updated to note that it does not cause all logical breakpoints
+      to be replicated in the output file.
+
+    - Fix issue git #41, typo in manual regarding -fsb.
+
+    - Fix issue git #40: when using the -bli option, a closing brace followed by 
+      a semicolon was not being indented.  This applies to braces which require 
+      semicolons, such as a 'do' block.
+
+    - Added 'state' as a keyword.
+
+    - 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
+ 
+        use overload
+          '+' => sub {
+          ...
+
+    - A number of minor problems with parsing signatures and prototypes have
+      been corrected, particularly multi-line signatures. Some signatures 
+      had previously been parsed as if they were prototypes, which meant the 
+      normal spacing rules were not applied.  For example
+   
+      OLD:
+        sub echo ($message= 'Hello World!' ) {
+            ...;
+        }
+
+      NEW:
+        sub echo ( $message = 'Hello World!' ) {
+            ...;
+        }
+
+    - Numerous minor issues that the average user would not encounter were found
+      and fixed. They can be seen in the more complete list of updates at 
+
+           https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2020 10 01
+
+    - Robustness of perltidy has been significantly improved.  Updating is recommended. Continual 
+      automated testing runs began about 1 Sep 2020 and numerous issues have been found and fixed. 
+      Many involve references to uninitialized variables when perltidy is fed random text and random
+      control parameters. 
+
+    - Added the token '->' to the list of alignment tokens, as suggested in git
+      #39, so that it can be vertically aligned if a space is placed before them with -wls='->'.
+
+    - Added parameters -bbhb=n (--break-before-hash-brace=n), -bbsb=n (--break-before-square-bracket=n),
+      and -bbp=n (--break-before-paren=n) suggested in git #38.  These provide control over the
+      opening container token of a multiple-line list.  Related new parameters -bbhbi=n, -bbsbi=n, -bbpi=n
+      control indentation of these tokens.
+
+    - Added keyword 'isa'.
+
+## 2020 09 07
+
+    - Fixed bug git #37, an error when the combination -scbb -csc was used.
+      It occurs in perltidy versions 20200110, 20200619, and 20200822.  What happens is
+      that when two consecutive lines with isolated closing braces had new side
+      comments generated by the -csc parameter, a separating newline was missing.
+      The resulting script will not then run, but worse, if it is reformatted with
+      the same parameters then closing side comments could be overwritten and data
+      lost. 
+
+      This problem was found during automated random testing.  The parameter
+      -scbb is rarely used, which is probably why this has not been reported.  Please
+      upgrade your version.
+
+    - Added parameter --non-indenting-braces, or -nib, which prevents
+      code from indenting one level if it follows an opening brace marked 
+      with a special side comment, '#<<<'.  For example,
+
+                    { #<<<   a closure to contain lexical vars
+
+                    my $var;  # this line does not indent
+
+                    }
+
+                    # this line cannot 'see' $var;
+
+      This is on by default.  If your code happens to have some
+      opening braces followed by '#<<<', and you
+      don't want this, you can use -nnib to deactivate it. 
+
+    - Side comment locations reset at a line ending in a level 0 open
+      block, such as when a new multi-line sub begins.  This is intended to 
+      help keep side comments from drifting to far to the right.
+
+## 2020 08 22
+
+    - Fix RT #133166, encoding not set for -st.  Also reported as RT #133171
+      and git #35. 
+
+      This is a significant bug in version 20200616 which can corrupt data if
+      perltidy is run as a filter on encoded text.
+**Please upgrade**
+
+    - Fix issue RT #133161, perltidy -html was not working on pod
+
+    - Fix issue git #33, allow control of space after '->'
+
+    - Vertical alignment has been improved. Numerous minor issues have
+      been fixed.
+
+    - Formatting with the -lp option is improved. 
+
+    - Fixed issue git #32, misparse of bare 'ref' in ternary
+
+    - When --assert-tidy is used and triggers an error, the first difference
+      between input and output files is shown in the error output. This is
+      a partial response to issue git #30.
+
+## 2020 06 19
+
+    - Added support for Switch::Plain syntax, issue git #31.
+
+    - Fixed minor problem where trailing 'unless' clauses were not 
+      getting vertically aligned.
+
+    - Added a parameter --logical-padding or -lop to allow logical padding
+      to be turned off.  Requested by git #29. This flag is on by default.
+      The man pages have examples.
+
+    - Added a parameter -kpit=n to control spaces inside of parens following
+      certain keywords, requested in git#26. This flag is off by default.
+
+    - Added fix for git#25, improve vertical alignment for long lists with
+      varying numbers of items per line.
+
+    - calls to the module Perl::Tidy can now capture any output produced
+      by a debug flag or one of the 'tee' flags through the new 'debugfile' and
+      'teefile' call parameters.  These output streams are rarely used but
+      they are now treated the same as any 'logfile' stream.
+
+    - add option --break-at-old-semicolon-breakpoints', -bos, requested 
+      in RT#131644.  This flag will keep lines beginning with a semicolon.
+
+    - Added --use-unicode-gcstring to control use of Unicode::GCString for
+      evaluating character widths of encoded data.  The default is 
+      not to use this (--nouse-unicode-gcstring). If this flag is set,
+      perltidy will look for Unicode::GCString and, if found, will use it 
+      to evaluate character display widths.  This can improve displayed
+      vertical alignment for files with wide characters.  It is a nice
+      feature but it is off by default to avoid conflicting formatting
+      when there are multiple developers.  Perltidy installation does not 
+      require Unicode::GCString, so users wanting to use this feature need 
+      set this flag and also to install Unicode::GCString separately.
+
+    - Added --character-encoding=guess or -guess to have perltidy guess
+      if a file (or other input stream) is encoded as -utf8 or some 
+      other single-byte encoding. This is useful when processing a mixture 
+      of file types, such as utf8 and latin-1.
+
+      Please Note: The default encoding has been set to be 'guess'
+      instead of 'none'. This seems like the best default, since 
+      it allows perltidy work properly with both
+      utf8 files and older latin-1 files.  The guess mode uses Encode::Guess,
+      which is included in standard perl distributions, and only tries to 
+      guess if a file is utf8 or not, never any other encoding.  If the guess is 
+      utf8, and if the file successfully decodes as utf8, then it the encoding 
+      is assumed to be utf8.  Otherwise, no encoding is assumed. 
+      If you do not want to use this new default guess mode, or have a 
+      problem with it, you can set --character-encoding=none (the previous 
+      default) or --character-encoding=utf8 (if you deal with utf8 files).
+
+    - Specific encodings of input files other than utf8 may now be given, for
+      example --character-encoding=euc-jp.
+
+    - Fix for git#22, Preserve function signature on a single line. An
+      unwanted line break was being introduced when a closing signature paren
+      followed a closing do brace.
+
+    - Fix RT#132059, the -dac parameter was not working and caused an error exit
+
+    - When -utf8 is used, any error output is encoded as utf8
+
+    - Fix for git#19, adjust line break around an 'xor'
+
+    - Fix for git#18, added warning for missing comma before unknown bare word.
+
 ## 2020 01 10
 
     - This release adds a flag to control the feature RT#130394 (allow short nested blocks)