From: Steve Hancock Date: Tue, 15 Feb 2022 01:53:47 +0000 (-0800) Subject: update docs before release X-Git-Tag: 20220217~4 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=a94765c9a1e1302be5f0542b5ced7f3c14e28371;p=perltidy.git update docs before release --- diff --git a/CHANGES.md b/CHANGES.md index 382cb3e6..b9aee8c2 100644 --- 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 035327c3..2a6329a7 100644 --- 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 aaa220bf..537ac8b7 100644 --- a/docs/Tidy.html +++ b/docs/Tidy.html @@ -101,14 +101,17 @@

If the destination parameter is given, it will be used to define the file or memory location to receive output of perltidy.

-

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 calling program and Perl::Tidy are in agreement regarding the state to be returned. A flag --encode-output-strings, or simply -eos, was added in versions of Perl::Tidy after 20220101 for this purpose. This flag should be added to the end of the argv paremeter (described below). The options are as follows.

+

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 --encode-output-strings, or simply -eos, was added in versions of Perl::Tidy after 20220101 for this purpose. This flag should be added to the end of the argv paremeter (described below). The options are as follows.

diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod index d271e530..7254d3b1 100644 --- a/lib/Perl/Tidy.pod +++ b/lib/Perl/Tidy.pod @@ -83,13 +83,14 @@ filenames may be specified in the @ARGV array or B parameter. If the B parameter is given, it will be used to define the file or memory location to receive output of perltidy. -B. Perl -strings of characters can be stored in one of two states, and it is important that the +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>, 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 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 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, so B<-neos> should still be set, if appropriate, to allow for the +possibility of a future change in the default. =back