update docs before release

diff --git a/CHANGES.md b/CHANGES.md
index 382cb3e6f91b528a5efb2539e6e128bf648ac332..b9aee8c260b51ab2c680be0b82f3ecbe538e4813 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,13 @@
       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
+      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

diff --git a/docs/ChangeLog.html b/docs/ChangeLog.html
index 035327c38dd16ba38023cb71bcfe79c41dd288cc..2a6329a78a6ffaeb61f17815dddf69ada1085062 100644 (file)
--- a/docs/ChangeLog.html
+++ b/docs/ChangeLog.html
@@ -17,6 +17,13 @@
   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
+  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

diff --git a/docs/Tidy.html b/docs/Tidy.html
index aaa220bfe0b28e10d397cdb15e1b74ac20b8abec..537ac8b78d64ec3f6321aacfb73cd5dd40b6e180 100644 (file)
--- a/docs/Tidy.html
+++ b/docs/Tidy.html
@@ -101,14 +101,17 @@
 
 <p>If the <b>destination</b> parameter is given, it will be used to define the file or memory location to receive output of perltidy.</p>
 
-<p><b>Important note if destination is a string or array reference</b>. Perl strings of characters can be stored in one of two states, and it is important that the calling program and Perl::Tidy are in agreement regarding the state to be returned. A flag <b>--encode-output-strings</b>, or simply <b>-eos</b>, was added in versions of Perl::Tidy after 20220101 for this purpose. This flag should be added to the end of the <b>argv</b> paremeter (described below). The options are as follows.</p>
+<p><b>Important note if destination is a string or array reference</b>. Perl strings of characters which are decoded as utf8 by Perl::Tidy can be returned in either of two possible states, decoded or encoded, and it is important that the calling program and Perl::Tidy are in agreement regarding the state to be returned. A flag <b>--encode-output-strings</b>, or simply <b>-eos</b>, was added in versions of Perl::Tidy after 20220101 for this purpose. This flag should be added to the end of the <b>argv</b> paremeter (described below). The options are as follows.</p>
 
 <ul>
 
 <li><p>Use <b>-eos</b> if Perl::Tidy should encode any string which it decodes. This is probably most convenient for most programs. But do not use this setting if the calling program will encode the data too, because double encoding will corrupt data.</p>
 
 </li>
-<li><p>Use <b>-neos</b> if a string should remain decoded if it was decoded by Perl::Tidy. This is appropriate if the calling program will handle any needed encoding before outputting the string. This is the current default, but it should still be set, if appropriate, to allow for the possibility of a future change in the default.</p>
+<li><p>Use <b>-neos</b> if a string should remain decoded if it was decoded by Perl::Tidy. This is appropriate if the calling program will handle any needed encoding before outputting the string.</p>
+
+</li>
+<li><p>The current default is <b>-neos</b>, but <b>the default could change in a future version</b>, so <b>-neos</b> should still be set, if appropriate, to allow for the possibility of a future change in the default.</p>
 
 </li>
 </ul>

diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod
index d271e530a0097e14b701ffa4556666da38e65273..7254d3b1fb87e41212531655757fc40b63f42f71 100644 (file)
--- a/lib/Perl/Tidy.pod
+++ b/lib/Perl/Tidy.pod
@@ -83,13 +83,14 @@ filenames may be specified in the @ARGV array or B<argv> parameter.
 If the B<destination> parameter is given, it will be used to define the
 file or memory location to receive output of perltidy.
 
-B<Important note if destination is a string or array reference>.  Perl
-strings of characters can be stored in one of two states, and it is important that the
+B<Important note if destination is a string or array reference>.  Perl strings
+of characters which are decoded as utf8 by Perl::Tidy can be returned in either
+of two possible states, decoded or encoded, and it is important that the
 calling program and Perl::Tidy are in agreement regarding the state to be
-returned.  A flag B<--encode-output-strings>, or simply B<-eos>, was added
-in versions of Perl::Tidy after 20220101 for this
-purpose. This flag should be added to the end of the B<argv> paremeter (described below).
-The options are as follows.
+returned.  A flag B<--encode-output-strings>, or simply B<-eos>, was added in
+versions of Perl::Tidy after 20220101 for this purpose. This flag should be
+added to the end of the B<argv> paremeter (described below).  The options are
+as follows.
 
 =over 4
 
@@ -105,8 +106,12 @@ encode the data too, because double encoding will corrupt data.
 Use B<-neos> if a string should remain decoded if it was decoded by Perl::Tidy.
 This is appropriate if
 the calling program will handle any needed encoding before outputting the string.
-This is the current default, but it should still be set, if appropriate,
-to allow for the possibility of a future change in the default.
+
+=item *
+
+The current default is B<-neos>, but B<the default could change in a future
+version>, so B<-neos> should still be set, if appropriate, to allow for the
+possibility of a future change in the default.
 
 =back