New upstream version 20160302

[perltidy.git] / bin / perltidy

diff --git a/bin/perltidy b/bin/perltidy
index 08097638caec02ddc37d92b958d91e0fdb7e6f0f..86bf60d5e794102d33923204b338413f1d145a09 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -501,12 +501,30 @@ Perltidy will pass your string to perl with the exception that it will
 add a B<-c> and B<-x> if appropriate.  The F<.LOG> file will show
 exactly what flags were passed to perl.
 
+=item B<-xs>,   B<--extended-syntax>      
+
+A problem with formatting Perl code is that some modules can introduce new
+syntax.  This flag allows perltidy to handle certain common extensions
+to the standard syntax without complaint.  
+
+For example, without this flag a structure such as the following would generate
+a syntax error and the braces would not be balanced:
+
+    method deposit( Num $amount) {
+        $self->balance( $self->balance + $amount );
+    }
+
+This flag is enabled by default but it can be deactivated with B<-nxs>.
+Probably the only reason to deactivate this flag is to generate more diagnostic
+messages when debugging a script.
+
+
 =item B<-io>,   B<--indent-only>       
 
-This flag is used to deactivate all formatting and line break changes
+This flag is used to deactivate all whitespace and line break changes
 within non-blank lines of code.
 When it is in effect, the only change to the script will be
-to the indentation and blank lines.
+to the indentation and to the number of blank lines.
 And any flags controlling whitespace and newlines will be ignored.  You
 might want to use this if you are perfectly happy with your whitespace
 and line breaks, and merely want perltidy to handle the indentation.
@@ -520,6 +538,34 @@ B<--freeze-whitespace>.
 If you also want to keep your existing blank lines exactly
 as they are, you can add B<--freeze-blank-lines>. 
 
+With this option perltidy is still free to modify the indenting (and
+outdenting) of code and comments as it normally would.  If you also want to
+prevent long comment lines from being outdented, you can add either B<-noll> or
+B<-l=0>.
+
+Setting this flag will prevent perltidy from doing any special operations on
+closing side comments.  You may still delete all side comments however when
+this flag is in effect.
+
+
+=item B<-enc=s>,  B<--character-encoding=s>
+
+where B<s>=B<none> or B<utf8>.  This flag tells perltidy the character encoding
+of both the input and output character streams.  The value B<utf8> causes the
+stream to be read and written as UTF-8.  The value B<none> causes the stream to
+be processed without special encoding assumptions.  At present there is no
+automatic detection of character encoding (even if there is a C<'use utf8'>
+statement in your code) so this flag must be set for streams encoded in UTF-8.
+Incorrectly setting this parameter can cause data corruption, so please
+carefully check the output.
+
+The default is B<none>.  
+
+The abbreviations B<-utf8> or B<-UTF8> are equivalent to B<-enc=utf8>.
+So to process a file named B<file.pl> which is encoded in UTF-8 you can use:
+
+   perltidy -utf8 file.pl
+
 =item B<-ole=s>,  B<--output-line-ending=s>
 
 where s=C<win>, C<dos>, C<unix>, or C<mac>.  This flag tells perltidy
@@ -2577,8 +2623,8 @@ are preceded by the name of the alias (without leading dashes), like this:
        }
 
 where B<newword> is the abbreviation, and B<opt1>, etc, are existing parameters
-I<or other abbreviations>.  The main syntax requirement is that
-the new abbreviation must begin on a new line.
+I<or other abbreviations>.  The main syntax requirement is that the new
+abbreviation along with its opening curly brace must begin on a new line.
 Space before and after the curly braces is optional.
 For a
 specific example, the following line
@@ -3093,7 +3139,7 @@ perlstyle(1), Perl::Tidy(3)
 
 =head1 VERSION
 
-This man page documents perltidy version 20130922.
+This man page documents perltidy version 20160302.
 
 =head1 CREDITS