New upstream version 20160302

[perltidy.git] / docs / perltidy.1

diff --git a/docs/perltidy.1 b/docs/perltidy.1
index 4ad6877d11d25d734e64ddb48392e556ea3ca9eb..b2a3c6538a0a46c3da762971e9916797de4de401 100644 (file)
--- a/docs/perltidy.1
+++ b/docs/perltidy.1
@@ -124,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "PERLTIDY 1"
-.TH PERLTIDY 1 "2014-03-27" "perl v5.14.2" "User Contributed Perl Documentation"
+.TH PERLTIDY 1 "2016-03-01" "perl v5.14.2" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -615,12 +615,30 @@ if the taint flag, \f(CW\*(C`\-T\*(C'\fR, is not wanted, the flag could be set t
 Perltidy will pass your string to perl with the exception that it will
 add a \fB\-c\fR and \fB\-x\fR if appropriate.  The \fI.LOG\fR file will show
 exactly what flags were passed to perl.
+.IP "\fB\-xs\fR,   \fB\-\-extended\-syntax\fR" 4
+.IX Item "-xs,   --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.
+.Sp
+For example, without this flag a structure such as the following would generate
+a syntax error and the braces would not be balanced:
+.Sp
+.Vb 3
+\&    method deposit( Num $amount) {
+\&        $self\->balance( $self\->balance + $amount );
+\&    }
+.Ve
+.Sp
+This flag is enabled by default but it can be deactivated with \fB\-nxs\fR.
+Probably the only reason to deactivate this flag is to generate more diagnostic
+messages when debugging a script.
 .IP "\fB\-io\fR,   \fB\-\-indent\-only\fR" 4
 .IX Item "-io,   --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.
@@ -633,6 +651,34 @@ Setting this flag is equivalent to setting \fB\-\-freeze\-newlines\fR and
 .Sp
 If you also want to keep your existing blank lines exactly
 as they are, you can add \fB\-\-freeze\-blank\-lines\fR.
+.Sp
+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 \fB\-noll\fR or
+\&\fB\-l=0\fR.
+.Sp
+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.
+.IP "\fB\-enc=s\fR,  \fB\-\-character\-encoding=s\fR" 4
+.IX Item "-enc=s,  --character-encoding=s"
+where \fBs\fR=\fBnone\fR or \fButf8\fR.  This flag tells perltidy the character encoding
+of both the input and output character streams.  The value \fButf8\fR causes the
+stream to be read and written as \s-1UTF\-8\s0.  The value \fBnone\fR 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 \f(CW\*(Aquse utf8\*(Aq\fR
+statement in your code) so this flag must be set for streams encoded in \s-1UTF\-8\s0.
+Incorrectly setting this parameter can cause data corruption, so please
+carefully check the output.
+.Sp
+The default is \fBnone\fR.
+.Sp
+The abbreviations \fB\-utf8\fR or \fB\-UTF8\fR are equivalent to \fB\-enc=utf8\fR.
+So to process a file named \fBfile.pl\fR which is encoded in \s-1UTF\-8\s0 you can use:
+.Sp
+.Vb 1
+\&   perltidy \-utf8 file.pl
+.Ve
 .IP "\fB\-ole=s\fR,  \fB\-\-output\-line\-ending=s\fR" 4
 .IX Item "-ole=s,  --output-line-ending=s"
 where s=\f(CW\*(C`win\*(C'\fR, \f(CW\*(C`dos\*(C'\fR, \f(CW\*(C`unix\*(C'\fR, or \f(CW\*(C`mac\*(C'\fR.  This flag tells perltidy
@@ -2675,8 +2721,8 @@ are preceded by the name of the alias (without leading dashes), like this:
 .Ve
 .Sp
 where \fBnewword\fR is the abbreviation, and \fBopt1\fR, etc, are existing parameters
-\&\fIor other abbreviations\fR.  The main syntax requirement is that
-the new abbreviation must begin on a new line.
+\&\fIor other abbreviations\fR.  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
@@ -3183,7 +3229,7 @@ purpose of this rule is to prevent generating confusing filenames such as
 \&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3)
 .SH "VERSION"
 .IX Header "VERSION"
-This man page documents perltidy version 20140328.
+This man page documents perltidy version 20160302.
 .SH "CREDITS"
 .IX Header "CREDITS"
 Michael Cartmell supplied code for adaptation to \s-1VMS\s0 and helped with