New upstream version 20220613

[perltidy.git] / lib / Perl / Tidy.pod

diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod
index 0423b7e1ed1597518d8b9b7ff3857e0cf091b0cf..bbb6bfe466d676346d5da9ffcfb667c4622c55cd 100644 (file)
--- a/lib/Perl/Tidy.pod
+++ b/lib/Perl/Tidy.pod
@@ -1,3 +1,4 @@
+

 =head1 NAME
 
 Perl::Tidy - Parses and beautifies perl source
 =head1 NAME
 
 Perl::Tidy - Parses and beautifies perl source


@@ -37,8 +38,8 @@ For example, the perltidy script is basically just this:
 
 The call to B<perltidy> returns a scalar B<$error_flag> which is TRUE if an
 error caused premature termination, and FALSE if the process ran to normal
 
 The call to B<perltidy> returns a scalar B<$error_flag> which is TRUE if an
 error caused premature termination, and FALSE if the process ran to normal

-completion.  Additional discuss of errors is contained below in the L<ERROR
-HANDLING> section.
+completion.  Additional discuss of errors is contained below in the
+L<ERROR HANDLING|"ERROR HANDLING"> section.

 
 The module accepts input and output streams by a variety of methods.
 The following list of parameters may be any of the following: a
 
 The module accepts input and output streams by a variety of methods.
 The following list of parameters may be any of the following: a


@@ -88,50 +89,47 @@ 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
 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) if Perl::Tidy
-will be decoding utf8 text.  The options are as follows.
+Perl::Tidy version 20220217 for this purpose.

 
 =over 4
 
 =item *
 
 
 =over 4
 
 =item *
 

-Use B<-eos> 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.
+Use B<-eos> if Perl::Tidy should encode any string which it decodes.  This is
+the current default because it makes perltidy behave well as a filter, and is
+the correct setting for most programs.  But do not use this setting if the
+calling program will encode the data too, because double encoding will corrupt
+data.

 
 =item *
 
 Use B<-neos> if a string should remain decoded if it was decoded by Perl::Tidy.
 
 =item *
 
 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 only appropriate if the calling program will handle any needed encoding
+before outputting the string.  If needed, this flag can be added to the end of
+the B<argv> parameter passed to Perl::Tidy.

 
 

-=item *
+=back

 
 

-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.
+For some background information see
+L<https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md>.

 
 

-=back
+This change in default behavior was made over a period of time as follows:

 
 

-For example, to set B<-eos> the following could be used
+=over 4

 
 

-        $argv .= " -eos" if ( $Perl::Tidy::VERSION > 20220101 );
+=item *

 
 

-        $error_flag = Perl::Tidy::perltidy(
-            argv        => $argv,
-            source      => \$source,
-            destination => \$destination,
-            stderr      => \$stderr,
-            errorfile   => \$errorfile
-        );
+For versions before 20220217 the B<-eos> flag was not available and the behavior was equivalent to B<-neos>.

 
 

-The test on version allows older versions of Perl::Tidy to still be used.
+=item *

 
 

-For some background information see
-L<https://github.com/perltidy/perltidy/issues/83> and
-L<https://github.com/houseabsolute/perl-code-tidyall/issues/84>.
+In version 20220217 the B<-eos> flag was added but the default remained B<-neos>.
+
+=item *
+
+For versions after 20220217 the default was set to B<-eos>.
+
+=back

 
 =item B<stderr>
 
 
 =item B<stderr>
 


@@ -454,12 +452,7 @@ identifier is found, its actual text is checked to see if it is one
 being sought.  If so, the above write_line prints the token and its
 line number.
 
 being sought.  If so, the above write_line prints the token and its
 line number.
 

-The B<formatter> feature is relatively new in perltidy, and further
-documentation needs to be written to complete its description.  However,
-several example programs have been written and can be found in the
-B<examples> section of the source distribution.  Probably the best way
-to get started is to find one of the examples which most closely matches
-your application and start modifying it.
+The B<examples> section of the source distribution has some examples of programs which use the B<formatter> option.

 
 For help with perltidy's peculiar way of breaking lines into tokens, you
 might run, from the command line,
 
 For help with perltidy's peculiar way of breaking lines into tokens, you
 might run, from the command line,


@@ -470,7 +463,7 @@ where F<filename> is a short script of interest.  This will produce
 F<filename.DEBUG> with interleaved lines of text and their token types.
 The B<-D> flag has been in perltidy from the beginning for this purpose.
 If you want to see the code which creates this file, it is
 F<filename.DEBUG> with interleaved lines of text and their token types.
 The B<-D> flag has been in perltidy from the beginning for this purpose.
 If you want to see the code which creates this file, it is

-C<write_debug_entry> in Tidy.pm.
+C<sub Perl::Tidy::Debugger::write_debug_entry>

 
 =head1 EXPORT
 
 
 =head1 EXPORT
 


@@ -482,7 +475,7 @@ The module 'Perl::Tidy' comes with a binary 'perltidy' which is installed when t
 
 =head1 VERSION
 
 
 =head1 VERSION
 

-This man page documents Perl::Tidy version 20220217
+This man page documents Perl::Tidy version 20220613

 
 =head1 LICENSE
 
 
 =head1 LICENSE
 


@@ -493,12 +486,10 @@ Please refer to the file "COPYING" for details.
 
 =head1 BUG REPORTS
 
 
 =head1 BUG REPORTS
 

-A list of current bugs and issues can be found at the CPAN site L<https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
-
-To report a new bug or problem, use the link on this page.
-

 The source code repository is at L<https://github.com/perltidy/perltidy>.
 
 The source code repository is at L<https://github.com/perltidy/perltidy>.
 

+To report a new bug or problem, use the "issues" link on this page.
+

 =head1 SEE ALSO
 
 The perltidy(1) man page describes all of the features of perltidy.  It
 =head1 SEE ALSO
 
 The perltidy(1) man page describes all of the features of perltidy.  It