]> git.donarmstrong.com Git - perltidy.git/blobdiff - bin/perltidy
New upstream version 20170521
[perltidy.git] / bin / perltidy
index 6d55221485427e5af733b83d120246a3f31c11f4..174f792ab0b17455702263ac7971e4b07396fb4c 100755 (executable)
@@ -73,6 +73,10 @@ Modify F<file1.pl> and F<file2.pl> in place, and backup the originals to
 F<file1.pl.bak> and F<file2.pl.bak>.  If F<file1.pl.bak> and/or F<file2.pl.bak>
 already exist, they will be overwritten.
 
+  perltidy -b -bext='/' file1.pl file2.pl
+
+Same as the previous example except that the backup files F<file1.pl.bak> and F<file2.pl.bak> will be deleted if there are no errors.
+
   perltidy -gnu somefile.pl
 
 Execute perltidy on file F<somefile.pl> with a style which approximates the
@@ -137,7 +141,7 @@ The entire command line is scanned for options, and they are processed
 before any files are processed.  As a result, it does not matter
 whether flags are before or after any filenames.  However, the relative
 order of parameters is important, with later parameters overriding the
-values of earlier parameters.
+values of earlier parameters.  
 
 For each parameter, there is a long name and a short name.  The short
 names are convenient for keyboard input, while the long names are
@@ -146,7 +150,7 @@ use two leading dashes for long names, but one may be used.
 
 Most parameters which serve as on/off flags can be negated with a
 leading "n" (for the short name) or a leading "no" or "no-" (for the
-long name).  For example, the flag to outdent long quotes is is B<-olq>
+long name).  For example, the flag to outdent long quotes is B<-olq>
 or B<--outdent-long-quotes>.  The flag to skip this is B<-nolq>
 or B<--nooutdent-long-quotes> or B<--no-outdent-long-quotes>.
 
@@ -229,8 +233,13 @@ extension F<.bak>.  Any existing F<.bak> file will be deleted.  See next
 item for changing the default backup extension, and for eliminating the
 backup file altogether.  
 
-A B<-b> flag will be ignored if input is from standard input, or
-if the B<-html> flag is set. 
+A B<-b> flag will be ignored if input is from standard input or goes to
+standard output, or if the B<-html> flag is set.  
+
+In particular, if you want to use both the B<-b> flag and the B<-pbp>
+(--perl-best-practices) flag, then you must put a B<-nst> flag after the
+B<-pbp> flag because it contains a B<-st> flag as one of its components,
+which means that output will go to the standard output stream.
 
 =item  B<-bext>=ext,    B<--backup-file-extension>=ext  
 
@@ -361,6 +370,10 @@ set of F<.perltidyrc> files to avoid unwanted code tidying.  See also
 L<Skipping Selected Sections of Code> for a way to avoid tidying specific
 sections of code.
 
+=item B<-i=n>,  B<--indent-columns=n>  
+
+Use n columns per indentation level (default n=4).
+
 =item B<-l=n>, B<--maximum-line-length=n>
 
 The default maximum line length is n=80 characters.  Perltidy will try
@@ -368,9 +381,49 @@ to find line break points to keep lines below this length. However, long
 quotes and side comments may cause lines to exceed this length. 
 Setting B<-l=0> is equivalent to setting B<-l=(a large number)>. 
 
-=item B<-i=n>,  B<--indent-columns=n>  
+=item B<-vmll>, B<--variable-maximum-line-length>
 
-Use n columns per indentation level (default n=4).
+A problem arises using a fixed maximum line length with very deeply nested code
+and data structures because eventually the amount of leading whitespace used
+for indicating indentation takes up most or all of the available line width,
+leaving little or no space for the actual code or data.  One solution is to use
+a vary long line length.  Another solution is to use the B<-vmll> flag, which
+basically tells perltidy to ignore leading whitespace when measuring the line
+length.  
+
+To be precise, when the B<-vmll> parameter is set, the maximum line length of a
+line of code will be M+L*I, where
+
+      M is the value of --maximum-line-length=M (-l=M), default 80,
+      I is the value of --indent-columns=I (-i=I), default 4,
+      L is the indentation level of the line of code
+
+When this flag is set, the choice of breakpoints for a block of code should be
+essentially independent of its nesting depth.  However, the absolute line
+lengths, including leading whitespace, can still be arbitrarily large.  This
+problem can be avoided by including the next parameter.  
+
+The default is not to do this (B<-nvmll>).
+
+=item B<-wc=n>, B<--whitespace-cycle=n>
+
+This flag also addresses problems with very deeply nested code and data
+structures.  When the nesting depth exceeds the value B<n> the leading
+whitespace will be reduced and start at a depth of 1 again.  The result is that
+blocks of code will shift back to the left rather than moving arbitrarily far
+to the right.  This occurs cyclically to any depth.  
+
+For example if one level of indentation equals 4 spaces (B<-i=4>, the default),
+and one uses B<-wc=15>, then if the leading whitespace on a line exceeds about
+4*15=60 spaces it will be reduced back to 4*1=4 spaces and continue increasing
+from there.  If the whitespace never exceeds this limit the formatting remains
+unchanged.
+
+The combination of B<-vmll> and B<-wc=n> provides a solution to the problem of
+displaying arbitrarily deep data structures and code in a finite window,
+although B<-wc=n> may of course be used without B<-vmll>.
+
+The default is not to use this, which can also be indicated using B<-wc=0>.
 
 =item tabs
 
@@ -401,6 +454,19 @@ option, and if these options are also given, then a warning message will
 be issued and this flag will be unset.  One example is the B<-lp>
 option.
 
+=item B<-dt=n>,   B<--default-tabsize=n>
+
+If the first line of code passed to perltidy contains leading tabs but no
+tab scheme is specified for the output stream then perltidy must guess how many
+spaces correspond to each leading tab.  This number of spaces B<n>
+corresponding to each leading tab of the input stream may be specified with
+B<-dt=n>.  The default is B<n=8>.  
+
+This flag has no effect if a tab scheme is specified for the output stream,
+because then the input stream is assumed to use the same tab scheme and
+indentation spaces as for the output stream (any other assumption would lead to
+unstable editing).
+
 =back
 
 =item B<-syn>,   B<--check-syntax>      
@@ -435,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.
@@ -454,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
@@ -480,10 +592,21 @@ can be useful when a major style change is being made, or when code is being
 beautified on check-in to a source code control system.  It has been found to
 be extremely rare for the output to change after 2 iterations.  If a value
 B<n> is greater than 2 is input then a convergence test will be used to stop
-the iterations as soon as possible, almost always after 2 iterations.  
+the iterations as soon as possible, almost always after 2 iterations.  See
+the next item for a simplified iteration control.
 
 This flag has no effect when perltidy is used to generate html.
 
+=item B<-conv>,   B<--converge>
+
+This flag is equivalent to B<-it=4> and is included to simplify iteration
+control.  For all practical purposes one either does or does not want to be
+sure that the output is converged, and there is no penalty to using a large
+iteration limit since perltidy will check for convergence and stop iterating as
+soon as possible.  The default is B<-nconv> (no convergence check).  Using
+B<-conv> will approximately double run time since normally one extra iteration
+is required to verify convergence.
+
 =back
 
 =head2 Code Indentation Control
@@ -614,7 +737,7 @@ B<-cbi> or B<--closing-brace-indentation> controls non-block B<}>'s.
 
 The B<-icp> flag is equivalent to
 B<-cti=2>, described in the previous section.  The B<-nicp> flag is
-equivalent B<-cti=0>.  They are included for backwards compatability.
+equivalent B<-cti=0>.  They are included for backwards compatibility.
 
 =item B<-icb>, B<--indent-closing-brace>
 
@@ -664,7 +787,7 @@ Use B<-nola> to not outdent labels.
 
 =item B<-okw>,  B<--outdent-keywords>
 
-The command B<-okw> will will cause certain leading control keywords to
+The command B<-okw> will cause certain leading control keywords to
 be outdented by 2 spaces (or whatever B<-ci> has been set to), if
 possible.  By default, these keywords are C<redo>, C<next>, C<last>,
 C<goto>, and C<return>.  The intention is to make these control keywords
@@ -756,6 +879,23 @@ example below.
  %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.';   # -bbt=1
  %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.';     # -bbt=2
 
+To simplify input in the case that all of the tightness flags have the same
+value <n>, the parameter <-act=n> or B<--all-containers-tightness=n> is an
+abbreviation for the combination <-pt=n -sbt=n -bt=n -bbt=n>.
+
+
+=item B<-tso>,   B<--tight-secret-operators>
+
+The flag B<-tso> causes certain perl token sequences (secret operators)
+which might be considered to be a single operator to be formatted "tightly"
+(without spaces).  The operators currently modified by this flag are: 
+
+     0+  +0  ()x!! ~~<>  ,=>   =( )=  
+
+For example the sequence B<0 +>,  which converts a string to a number,
+would be formatted without a space: B<0+> when the B<-tso> flag is set.  This
+flag is off by default.
+
 =item B<-sts>,   B<--space-terminal-semicolon>
 
 Some programmers prefer a space before all terminal semicolons.  The
@@ -913,6 +1053,11 @@ multi-line C<qw> quotes to be left unchanged.  This option will not
 normally be necessary, but was added for testing purposes, because in
 some versions of perl, trimming C<qw> quotes changes the syntax tree.
 
+=item Trimming trailing whitespace from lines of POD
+
+B<-trp> or B<--trim-pod> will remove trailing whitespace from lines of POD.
+The default is not to do this.
+
 =back
 
 =head2 Comment Controls
@@ -964,7 +1109,25 @@ right.  The default is n=4 spaces.
 =item B<-fpsc=n>,  B<--fixed-position-side-comment=n>
 
 This parameter tells perltidy to line up side comments in column number B<n>
-whenever possible.  The default, n=0, is not do do this.
+whenever possible.  The default, n=0, will not do this.
+
+=item B<-iscl>,  B<--ignore-side-comment-lengths>
+
+This parameter causes perltidy to ignore the length of side comments when
+setting line breaks.  The default, B<-niscl>, is to include the length of 
+side comments when breaking lines to stay within the length prescribed
+by the B<-l=n> maximum line length parameter.  For example, the following
+long single line would remain intact with -l=80 and -iscl:
+
+     perltidy -l=80 -iscl
+        $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
+
+whereas without the -iscl flag the line will be broken:
+
+     perltidy -l=80
+        $vmsfile =~ s/;[\d\-]*$//
+          ;    # Clip off version number; we can use a newer version as well
+   
 
 =item B<-hsc>, B<--hanging-side-comments>
 
@@ -1089,7 +1252,7 @@ can still be achieved with -ncscb:
   perltidy -csc -ncscb
   } ## end foreach my $foo (sort { $b cmp $a ...
 
-However this causes a problem with editors editors which cannot recognize
+However this causes a problem with editors which cannot recognize
 comments or are not configured to do so because they cannot "bounce" around in
 the text correctly.  The B<-cscb> flag has been added to
 help them by appending appropriate balancing structure:
@@ -1279,7 +1442,7 @@ single '#'.
 
 =item B<-osbc>, B<--outdent-static-block-comments>
 
-The command B<-osbc> will will cause static block comments to be outdented by 2
+The command B<-osbc> will cause static block comments to be outdented by 2
 spaces (or whatever B<-ci=n> has been set to), if possible.
 
 =back
@@ -1295,7 +1458,7 @@ when it is a side comment.
 =item B<-ssc>, B<--static-side-comments>
 
 When B<-ssc> is used, a side comment with a static leading pattern, which is
-C<##> by default, will be be spaced only a single space from previous
+C<##> by default, will be spaced only a single space from previous
 character, and it will not be vertically aligned with other side comments.
 
 The default is B<-nssc>.
@@ -1543,7 +1706,7 @@ comma and an opening token.  For example:
         description => $ref->{description}
       };
 
-The flag B<-otr> is actually a synonym for three other flags
+The flag B<-otr> is actually an abbreviation for three other flags
 which can be used to control parens, hash braces, and square brackets
 separately if desired:
 
@@ -1589,7 +1752,7 @@ between tightness and readability in complex lists.
 
 =item *
 
-Different controls may be applied to to different token types,
+Different controls may be applied to different token types,
 and it is also possible to control block braces; see below.
 
 =item *
@@ -1728,8 +1891,9 @@ C<elsif>, and C<else> blocks, we could use
 C<perltidy -bli -bbvt=1 -bbvtl='if elsif else'>.
 
 There is no vertical tightness control for closing block braces; with
-the exception of one-line blocks, they will normally remain on a 
-separate line.
+one exception they will be placed on separate lines.
+The exception is that a cascade of closing block braces may
+be stacked on a single line.  See B<-scbb>.
 
 =item B<-sot>,  B<--stack-opening-tokens> and related flags
 
@@ -1761,8 +1925,13 @@ controls can be used:
   -sop  or --stack-opening-paren
   -sohb or --stack-opening-hash-brace
   -sosb or --stack-opening-square-bracket
+  -sobb or --stack-opening-block-brace
+
+The flag B<-sot> is an abbreviation for B<-sop -sohb -sosb>.
 
-The flag B<-sot> is a synonym for B<-sop -sohb -sosb>.
+The flag B<-sobb> is a abbreviation for B<-bbvt=2 -bbvtl='*'>.  This
+will case a cascade of opening block braces to appear on a single line,
+although this an uncommon occurrence except in test scripts. 
 
 =item B<-sct>,  B<--stack-closing-tokens> and related flags
 
@@ -1808,8 +1977,26 @@ following controls can be used:
   -scp  or --stack-closing-paren
   -schb or --stack-closing-hash-brace
   -scsb or --stack-closing-square-bracket
+  -scbb or --stack-closing-block-brace
+
+The flag B<-sct> is an abbreviation for stacking the non-block closing
+tokens, B<-scp -schb -scsb>. 
+
+Stacking of closing block braces, B<-scbb>, causes a cascade of isolated
+closing block braces to be combined into a single line as in the following
+example:
+
+    # -scbb:
+    for $w1 (@w1) {
+        for $w2 (@w2) {
+            for $w3 (@w3) {
+                for $w4 (@w4) {
+                    push( @lines, "$w1 $w2 $w3 $w4\n" );
+                } } } }
 
-The flag B<-sct> is a synonym for B<-scp -schb -scsb>.
+To simplify input even further for the case in which both opening and closing
+non-block containers are stacked, the flag B<-sac> or B<--stack-all-containers>
+is an abbreviation for B<-sot -sot>.
 
 =item B<-dnl>,  B<--delete-old-newlines>
 
@@ -1956,18 +2143,22 @@ of perltidy.
 
 =item B<-cab=n>,  B<--comma-arrow-breakpoints=n>
 
-A comma which follows a comma arrow, '=>', requires special
+A comma which follows a comma arrow, '=>', is given special
 consideration.  In a long list, it is common to break at all such
 commas.  This parameter can be used to control how perltidy breaks at
 these commas.  (However, it will have no effect if old comma breaks are
 being forced because B<-boc> is used).  The possible values of B<n> are:
 
  n=0 break at all commas after =>  
- n=1 stable: break at all commas after => unless this would break
-     an existing one-line container (default)
- n=2 break at all commas after =>, but try to form the maximum
+ n=1 stable: break at all commas after => if container is open,
+     EXCEPT FOR one-line containers
+ n=2 break at all commas after =>, BUT try to form the maximum
      maximum one-line container lengths
  n=3 do not treat commas after => specially at all 
+ n=4 break everything: like n=0 but ALSO break a short container with
+     a => not followed by a comma when -vt=0 is used
+ n=5 stable: like n=1 but ALSO break at open one-line containers when
+     -vt=0 is used (default)
 
 For example, given the following single line, perltidy by default will
 not add any line breaks because it would break the existing one-line
@@ -1985,8 +2176,8 @@ Using B<-cab=0> will force a break after each comma-arrow item:
 
 If perltidy is subsequently run with this container broken, then by
 default it will break after each '=>' because the container is now
-broken.  To reform a one-line container, the parameter B<-cab=2> would
-be needed.
+broken.  To reform a one-line container, the parameter B<-cab=2> could
+be used.
 
 The flag B<-cab=3> can be used to prevent these commas from being
 treated specially.  In this case, an item such as "01" => 31 is
@@ -2089,7 +2280,7 @@ With B<perltidy -kis> the multiple statements are retained:
 
 The statements are still subject to the specified value
 of B<maximum-line-length> and will be broken if this 
-maximum is exceeed.
+maximum is exceeded.
 
 =back
 
@@ -2120,7 +2311,7 @@ The parameter B<-blbs=n> requests that least B<n> blank lines precede a sub
 definition which does not follow a comment and which is more than one-line
 long.  The default is <-blbs=1>.  B<BEGIN> and B<END> blocks are included.
 
-The requested number of blanks statement will be inserted regardless of of the
+The requested number of blanks statement will be inserted regardless of the
 value of B<--maximum-consecutive-blank-lines=n> (B<-mbl=n>) with the exception
 that if B<-mbl=0> then no blanks will be output.
 
@@ -2140,7 +2331,7 @@ value specified on the B<-mbl=k> flag.
 =item B<-blbp=n>,  B<--blank-lines-before-packages=n>
 
 The parameter B<-blbp=n> requests that least B<n> blank lines precede a package
-which does not follow a comment.  The default is <-blbp=1>.  
+which does not follow a comment.  The default is B<-blbp=1>.  
 
 This parameter interacts with the value B<k> of the parameter
 B<--maximum-consecutive-blank-lines=k> (B<-mbl=k>) in the same way as described
@@ -2149,7 +2340,7 @@ for the previous item B<-blbs=n>.
 
 =item B<-bbs>,  B<--blanks-before-subs>
 
-For compatability with previous versions, B<-bbs> or B<--blanks-before-subs> 
+For compatibility with previous versions, B<-bbs> or B<--blanks-before-subs>
 is equivalent to F<-blbp=1> and F<-blbs=1>.  
 
 Likewise, B<-nbbs> or B<--noblanks-before-subs> 
@@ -2188,6 +2379,60 @@ This controls how often perltidy is allowed to add blank lines before
 certain block types (see previous section).  The default is 8.  Entering
 a value of B<0> is equivalent to entering a very large number.
 
+=item B<-blao=i> or B<--blank-lines-after-opening-block=i>
+
+This control places a minimum of B<i> blank lines B<after> a line which B<ends>
+with an opening block brace of a specified type.  By default, this only applies
+to the block of a named B<sub>, but this can be changed (see B<-blaol> below).
+The default is not to do this (B<i=0>).
+
+Please see the note below on using the B<-blao> and B<-blbc> options.
+
+=item B<-blbc=i> or B<--blank-lines-before-closing-block=i>
+
+This control places a minimum of B<i> blank lines B<before> a line which
+B<begins> with a closing block brace of a specified type.  By default, this
+only applies to the block of a named B<sub>, but this can be changed (see
+B<-blbcl> below).  The default is not to do this (B<i=0>).
+
+=item B<-blaol=s> or B<--blank-lines-after-opening-block-list=s>
+
+The parameter B<s> is a list of block type keywords to which the flag B<-blao>
+should apply.  The section L<"Specifying Block Types"> explains how to list
+block types.
+
+=item B<-blbcl=s> or B<--blank-lines-before-closing-block-list=s>
+
+This parameter is a list of block type keywords to which the flag B<-blbc>
+should apply.  The section L<"Specifying Block Types"> explains how to list
+block types.
+
+=item Note on using the B<-blao> and B<-blbc> options.
+
+These blank line controls introduce a certain minimum number of blank lines in
+the text, but the final number of blank lines may be greater, depending on
+values of the other blank line controls and the number of old blank lines.  A
+consequence is that introducing blank lines with these and other controls
+cannot be exactly undone, so some experimentation with these controls is
+recommended before using them.
+
+For example, suppose that for some reason we decide to introduce one blank
+space at the beginning and ending of all blocks.  We could do
+this using
+
+  perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
+
+Now suppose the script continues to be developed, but at some later date we
+decide we don't want these spaces after all. we might expect that running with
+the flags B<-blao=0> and B<-blbc=0> will undo them.  However, by default
+perltidy retains single blank lines, so the blank lines remain.  
+
+We can easily fix this by telling perltidy to ignore old blank lines by
+including the added parameter B<-kbl=0> and rerunning. Then the unwanted blank
+lines will be gone.  However, this will cause all old blank lines to be
+ignored, perhaps even some that were added by hand to improve formatting. So
+please be cautious when using these parameters.
+
 =item B<-mbl=n> B<--maximum-consecutive-blank-lines=n>   
 
 This parameter specifies the maximum number of consecutive blank lines which
@@ -2215,12 +2460,12 @@ The default is B<n=1>.
 
 =item B<-sob>,  B<--swallow-optional-blank-lines>
 
-This is equivalent to B<kbl=0> and is included for compatability with
+This is equivalent to B<kbl=0> and is included for compatibility with
 previous versions.
 
 =item B<-nsob>,  B<--noswallow-optional-blank-lines>
 
-This is equivalent to B<kbl=1> and is included for compatability with
+This is equivalent to B<kbl=1> and is included for compatibility with
 previous versions.
 
 =back
@@ -2248,8 +2493,38 @@ by Damian Conway:
     -wbb="% + - * / x != == >= <= =~ !~ < > | & = 
           **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
 
-Note that the -st and -se flags make perltidy act as a filter on one file only.  
-These can be overridden with -nst and -nse if necessary.
+Please note that this parameter set includes -st and -se flags, which make
+perltidy act as a filter on one file only.  These can be overridden by placing
+B<-nst> and/or B<-nse> after the -pbp parameter. 
+
+Also note that the value of continuation indentation, -ci=4, is equal to the
+value of the full indentation, -i=4.  In some complex statements perltidy will
+produce nicer results with -ci=2. This can be implemented by including -ci=2
+after the -pbp parameter.  For example, 
+
+    # perltidy -pbp
+    $self->{_text} = (
+         !$section        ? ''
+        : $type eq 'item' ? "the $section entry"
+        :                   "the section on $section"
+        )
+        . (
+        $page
+        ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
+        : ' elsewhere in this document'
+        );
+
+    # perltidy -pbp -ci=2
+    $self->{_text} = (
+         !$section        ? ''
+        : $type eq 'item' ? "the $section entry"
+        :                   "the section on $section"
+      )
+      . (
+        $page
+        ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
+        : ' elsewhere in this document'
+      );
 
 =back
 
@@ -2312,7 +2587,7 @@ have a leading dot.  Further system-dependent information will be found
 in the INSTALL file distributed with perltidy.
 
 Under Windows, perltidy will also search for a configuration file named perltidy.ini since Windows does not allow files with a leading period (.).
-Use C<perltidy -dpro> to see the possbile locations for your system.
+Use C<perltidy -dpro> to see the possible locations for your system.
 An example might be F<C:\Documents and Settings\All Users\perltidy.ini>.
 
 Another option is the use of the PERLTIDY environment variable.
@@ -2328,7 +2603,7 @@ configuration file common to all users on the machine.  Be sure to enter the
 full path of the configuration file in the value of the environment variable.
 Ex.  PERLTIDY=C:\Documents and Settings\perltidy.ini
 
-The configuation file is free format, and simply a list of parameters, just as
+The configuration file is free format, and simply a list of parameters, just as
 they would be entered on a command line.  Any number of lines may be used, with
 any number of parameters per line, although it may be easiest to read with one
 parameter per line.  Comment text begins with a #, and there must
@@ -2402,8 +2677,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
@@ -2517,6 +2792,11 @@ B<--dump-want-right-space> or B<-dwrs>  will write the hash %want_right_space
 to standard output and quit.  See the section on controlling whitespace
 around tokens.
 
+B<--no-memoize> or B<-nmem>  will turn of memoizing.
+Memoization can reduce run time when running perltidy repeatedly in a 
+single process.  It is on by default but can be deactivated for
+testing with B<-nmem>.
+
 B<-DEBUG>  will write a file with extension F<.DEBUG> for each input file 
 showing the tokenization of all lines of code.
 
@@ -2799,7 +3079,10 @@ Several parameters which refer to code block types may be customized by also
 specifying an associated list of block types.  The type of a block is the name
 of the keyword which introduces that block, such as B<if>, B<else>, or B<sub>.
 An exception is a labeled block, which has no keyword, and should be specified
-with just a colon.
+with just a colon.  To specify all blocks use B<'*'>.
+
+The keyword B<sub> indicates a named sub.  For anonymous subs, use the special
+keyword B<asub>.
 
 For example, the following parameter specifies C<sub>, labels, C<BEGIN>, and
 C<END> blocks:
@@ -2808,7 +3091,10 @@ C<END> blocks:
 
 (the meaning of the -cscl parameter is described above.)  Note that
 quotes are required around the list of block types because of the
-spaces.
+spaces.  For another example, the following list specifies all block types
+for vertical tightness:
+
+   -bbvtl='*'
 
 =head2 Specifying File Extensions
 
@@ -2834,7 +3120,7 @@ The following list shows all short parameter names which allow a prefix
  D    anl asc  aws  b    bbb bbc bbs  bl   bli  boc bok  bol  bot  ce
  csc  dac dbc  dcsc ddf  dln dnl dop  dp   dpro dsc dsm  dsn  dtt  dwls
  dwrs dws f    fll  frm  fs  hsc html ibc  icb  icp iob  isbc lal  log
- lp   lsl ohbr okw  ola  oll opr opt  osbr otr  ple ple  pod  pvl  q
+ lp   lsl ohbr okw  ola  oll opr opt  osbr otr  ple  pod  pvl  q
  sbc  sbl schb scp  scsb sct se  sfp  sfs  skp  sob sohb sop  sosb sot
  ssc  st  sts  syn  t    tac tbc toc  tp   tqw  tsc w    x    bar  kis
 
@@ -2910,32 +3196,19 @@ perlstyle(1), Perl::Tidy(3)
 
 =head1 VERSION
 
-This man page documents perltidy version 20120701.
-
-=head1 CREDITS
-
-Michael Cartmell supplied code for adaptation to VMS and helped with
-v-strings.
-
-Yves Orton supplied code for adaptation to the various versions
-of Windows. 
-
-Axel Rose supplied a patch for MacPerl.
+This man page documents perltidy version 20170521.
 
-Hugh S. Myers designed and implemented the initial Perl::Tidy module interface. 
+=head1 BUG REPORTS
 
-Many others have supplied key ideas, suggestions, and bug reports;
-see the CHANGES file.
+A list of current bugs and issues can be found at the CPAN site
 
-=head1 AUTHOR
+     https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy
 
-  Steve Hancock
-  email: perltidy at users.sourceforge.net
-  http://perltidy.sourceforge.net
+To report a new bug or problem, use the link on this page.  
 
 =head1 COPYRIGHT
 
-Copyright (c) 2000-2010 by Steve Hancock
+Copyright (c) 2000-2017 by Steve Hancock
 
 =head1 LICENSE