update docs

diff --git a/CHANGES.md b/CHANGES.md
index b11ed0939316ad0dfabbccfbc51d332de71b4370..b497cf3703eee882681360ee024da892d0ddfc72 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -2,6 +2,25 @@
 
 ## 2021 10 29.06
 
+    - 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 'tidyall' in particular.  The crux of the matter is
+      that perltidy by default returns decoded character strings to the calling
+      program.  This is a result of its evolution over time, and it is not the best
+      default, but it is difficult to change without breaking existing programs.
+      Programs or users who require encoded character strings can set this flag.
+      In particular, tidyall users who process encoded (utf8) files should
+      probably set -eos to avoid problems. If you run the 'perltidy' binary
+      this flag has no effect.
+
+    - 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 was a bad idea and could lead
+      to problems 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 as requested
       in git #86.  This controls line breaks after labels, as follows:
@@ -26,23 +45,6 @@
     - Fix issue git #82, an error handling something like ${bareword} in a possible
       indirect object location.
 
-    - 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 was a bad idea and could lead
-      to problems 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, --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 tidyall in particular.  If you use tidyall and have
-      encoded files you may want to set this flag.  The crux of the matter is
-      that by default perltidy returns unencoded strings to the calling program.
-      Some programs need encoded strings, and setting this flag causes encoding.
-      If you use tidyall with encoded files (like utf8) you should probably
-      set this flag.  If you run the perltidy binary this flag has no effect.
-
     - 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

diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm
index 33018ee9b27fa6e73f5447a06fc408a5b0923372..b0c9842435695558ba8f1010ab1f710c1b1217c8 100644 (file)
--- a/lib/Perl/Tidy.pm
+++ b/lib/Perl/Tidy.pm
@@ -1677,10 +1677,13 @@ EOM
             # output to a string or array ref. We use the -eos flag to decide
             # if we should encode.
 
-            # [DEFAULT]: encoding is done by the program which writes to the
-            # file system. In this case, we do not encode string output.
+            # [DEFAULT]: perltidy does not return encoded string output.  This
+            # is a result of the code evolution but not very convenient for most
+            # applications.  It would be hard to change without breaking some
+            # programs.
 
-            # [WITH -eos flag]: encoding is done by the program which decodes.
+            # [WITH -eos flag]: If perltidy decodes a string, regardless of
+            # source, it encodes before returning.
 
             if ( $rOpts->{'encode-output-strings'} && $decoded_input_as ) {
                 my $encoded_buffer;

diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod
index 081d3c955b9820cbec3856e564625599321567b7..f42ba127c22e601847a28802c75adbbc5254240c 100644 (file)
--- a/lib/Perl/Tidy.pod
+++ b/lib/Perl/Tidy.pod
@@ -88,13 +88,14 @@ characters, then by default it will NOT be encoded by Perl::Tidy.
 
 This default is not always convenient, particularly if the calling program did
 not do the decoding, and can be changed by including the B<-eos> or
-B<--encode-output-strings> flag described in the B<perltidy> manual.  When this
-flag is set, and if Perl::Tidy decoded a string, then it will encode the string
-before returning. For some background information see the discussion at github
-for perltidy issue git #83 at
+B<--encode-output-strings> flag described in the B<perltidy> manual.  This can
+either be set by the user or by the calling program in the B<argv> parameter
+described below.  When this flag is set, and if Perl::Tidy decoded a string,
+then it will encode the string before returning. For some background
+information see the discussion at github for perltidy issue git #83 at
 L<https://github.com/perltidy/perltidy/issues/83>.
 
-This B<-eos> parameter was added after perltidy version 20211029.05.
+This B<-eos> parameter is available in perltidy version 20211029.06 and later.
 
 =item stderr