+ # perltidy -pbp -xci
+ $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'
+ );
+
+The B<-xci> flag was developed after the B<-pbp> parameters were published so you need
+to include it separately.
+
+=item B<One-line blocks>
+
+There are a few points to note regarding one-line blocks. A one-line
+block is something like this,
+
+ if ( -e $file ) { print "'$file' exists\n" }
+
+where the contents within the curly braces is short enough to fit
+on a single line.
+
+With few exceptions, perltidy retains existing one-line blocks, if it
+is possible within the line-length constraint, but it does not attempt
+to form new ones. In other words, perltidy will try to follow the
+one-line block style of the input file.
+
+If an existing one-line block is longer than the maximum line length,
+however, it will be broken into multiple lines. When this happens, perltidy
+checks for and adds any optional terminating semicolon (unless the B<-nasc>
+option is used) if the block is a code block.
+
+The main exception is that perltidy will attempt to form new one-line
+blocks following the keywords C<map>, C<eval>, and C<sort>, because
+these code blocks are often small and most clearly displayed in a single
+line.
+
+One-line block rules can conflict with the cuddled-else option. When
+the cuddled-else option is used, perltidy retains existing one-line
+blocks, even if they do not obey cuddled-else formatting.
+
+Occasionally, when one-line blocks get broken because they exceed the
+available line length, the formatting will violate the requested brace style.
+If this happens, reformatting the script a second time should correct
+the problem.
+
+Sometimes it might be desirable to convert a script to have one-line blocks
+whenever possible. Although there is currently no flag for this, a simple
+workaround is to execute perltidy twice, once with the flag B<-noadd-newlines>
+and then once again with normal parameters, like this:
+
+ cat infile | perltidy -nanl | perltidy >outfile
+
+When executed on this snippet
+
+ if ( $? == -1 ) {
+ die "failed to execute: $!\n";
+ }
+ if ( $? == -1 ) {
+ print "Had enough.\n";
+ die "failed to execute: $!\n";
+ }
+
+the result is
+
+ if ( $? == -1 ) { die "failed to execute: $!\n"; }
+ if ( $? == -1 ) {
+ print "Had enough.\n";
+ die "failed to execute: $!\n";
+ }
+
+This shows that blocks with a single statement become one-line blocks.
+
+=item B<-olbs=n>, B<--one-line-block-semicolons=n>
+
+This flag controls the placement of semicolons at the end of one-line blocks.
+Semicolons are optional before a closing block brace, and frequently they are
+omitted at the end of a one-line block containing just a single statement.
+By default, perltidy follows the input file regarding these semicolons,
+but this behavior can be controlled by this flag. The values of n are:
+
+ n=0 remove terminal semicolons in one-line blocks having a single statement
+ n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
+ n=2 add terminal semicolons in all one-line blocks
+
+Note that the B<n=2> option has no effect if adding semicolons is prohibited
+with the B<-nasc> flag. Also not that while B<n=2> adds missing semicolons to
+all one-line blocks, regardless of complexity, the B<n=0> option only removes
+ending semicolons which terminate one-line blocks containing just one
+semicolon. So these two options are not exact inverses.
+
+=item B<-olbn=n>, B<--one-line-block-nesting=n>
+
+Nested one-line blocks are lines with code blocks which themselves contain code
+blocks. For example, the following line is a nested one-line block.
+
+ foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
+
+The default behavior is to break such lines into multiple lines, but this
+behavior can be controlled with this flag. The values of n are:
+
+ n=0 break nested one-line blocks into multiple lines [DEFAULT]
+ n=1 stable: keep existing nested-one line blocks intact
+
+For the above example, the default formatting (B<-olbn=0>) is
+
+ foreach (@list) {
+ if ( $_ eq $asked_for ) { last }
+ ++$found;
+ }
+
+If the parameter B<-olbn=1> is given, then the line will be left intact if it
+is a single line in the source, or it will be broken into multiple lines if it
+is broken in multiple lines in the source.
+
+
+=back
+
+
+=head2 Controlling Vertical Alignment
+
+Vertical alignment refers to lining up certain symbols in a list of consecutive
+similar lines to improve readability. For example, the "fat commas" are
+aligned in the following statement:
+
+ $data = $pkg->new(
+ PeerAddr => join( ".", @port[ 0 .. 3 ] ),
+ PeerPort => $port[4] * 256 + $port[5],
+ Proto => 'tcp'
+ );
+
+Vertical alignment can be completely turned off using the B<-novalign> flag
+mentioned below. However, vertical alignment can be forced to
+stop and restart by selectively introducing blank lines. For example, a blank
+has been inserted in the following code to keep somewhat similar things
+aligned.
+
+ %option_range = (
+ 'format' => [ 'tidy', 'html', 'user' ],
+ 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
+ 'character-encoding' => [ 'none', 'utf8' ],
+
+ 'block-brace-tightness' => [ 0, 2 ],
+ 'brace-tightness' => [ 0, 2 ],
+ 'paren-tightness' => [ 0, 2 ],
+ 'square-bracket-tightness' => [ 0, 2 ],
+ );
+
+Vertical alignment is implemented by locally increasing an existing blank space
+to produce alignment with an adjacent line. It cannot occur if there is no
+blank space to increase. So if a particular space is removed by one of the
+existing controls then vertical alignment cannot occur. Likewise, if a space is
+added with one of the controls, then vertical alignment might occur.
+
+For example,
+
+ # perltidy -nwls='=>'
+ $data = $pkg->new(
+ PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
+ PeerPort=> $port[4] * 256 + $port[5],
+ Proto=> 'tcp'
+ );
+
+=over 4
+
+=item B<Completely turning off vertical alignment with -novalign>
+
+The default is to use vertical alignment, but bertical alignment can be
+completely turned of with the B<-novalign> flag.
+
+A lower level of control of vertical alignment is possible with three parameters
+B<-vc>, B<-vsc>, and B<-vbc>. These independently control alignment
+of code, side comments and block comments. They are described in the
+next section.
+
+The parameter B<-valign> is in fact an alias for B<-vc -vsc -vbc>, and its
+negative B<-novalign> is an alias for B<-nvc -nvsc -nvbc>.
+
+=item B<Controlling code alignment with --valign-code or -vc>
+
+The B<-vc> flag enables alignment of code symbols such as B<=>. The default is B<-vc>.
+For detailed control of which symbols to align, see the B<-valign-exclude-list> parameter
+below.
+
+=item B<Controlling side comment alignment with --valign-side-comments or -vsc>
+
+The B<-vsc> flag enables alignment of side comments and is enabled by default. If side
+comment aligment is disabled with B<-nvsc> they will appear at a fixed space from the
+preceding code token. The default is B<-vsc>
+
+=item B<Controlling block comment alignment with --valign-block-comments or -vbc>
+
+When B<-vbc> is enabled, block comments can become aligned for example if one
+comment of a consecutive sequence of comments becomes outdented due a length in
+excess of the maximum line length. If this occurs, the entire group of
+comments will remain aligned and be outdented by the same amount. This coordinated
+alignment will not occur if B<-nvbc> is set. The default is B<-vbc>.
+
+=item B<Finer alignment control with --valign-exclusion-list=s or -vxl=s and --valign-inclusion-list=s or -vil=s>
+
+More detailed control of alignment types is available with these two
+parameters. Most of the vertical alignments in typical programs occur at one
+of the tokens ',', '=', and '=>', but many other alignments are possible and are given in the following list:
+
+ = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
+ { ( ? : , ; => && || ~~ !~~ =~ !~ // <=> ->
+ if unless and or err for foreach while until
+
+These alignments are all enabled by default, but they can be selectively disabled by including one or more of these tokens in the space-separated list B<valign-exclusion-list=s>.
+For example, the following would prevent alignment at B<=> and B<if>:
+
+ --valign-exclusion-list='= if'
+
+If it is simpler to specify only the token types which are to be aligned, then
+include the types which are to be aligned in the list of B<--valign-inclusion-list>.
+You may leave the B<valign-exclusion-list> undefined, or use the special symbol B<*> for the exclusion list.
+For example, the following parameters enable alignment only at commas and 'fat commas':
+
+ --valign-inclusion-list=', =>'
+ --valign-exclusion-list='*' ( this is optional and may be omitted )
+
+These parameter lists should consist of space-separated tokens from the above
+list of possible alignment tokens, or a '*'. If an unrecognized token
+appears, it is simply ignored. And if a specific token is entered in both lists by
+mistake then the exclusion list has priority.
+
+The default values of these parameters enable all alignments and are equivalent to
+
+ --valign-exclusion-list=' '
+ --valign-inclusion-list='*'
+
+To illustrate, consider the following snippet with default formatting
+
+ # perltidy
+ $co_description = ($color) ? 'bold cyan' : ''; # description
+ $co_prompt = ($color) ? 'bold green' : ''; # prompt
+ $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
+
+To exclude all alignments except the equals (i.e., include only equals) we could use:
+
+ # perltidy -vil='='
+ $co_description = ($color) ? 'bold cyan' : ''; # description
+ $co_prompt = ($color) ? 'bold green' : ''; # prompt
+ $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
+
+To exclude only the equals we could use:
+
+ # perltidy -vxl='='
+ $co_description = ($color) ? 'bold cyan' : ''; # description
+ $co_prompt = ($color) ? 'bold green' : ''; # prompt
+ $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
+
+Notice in this last example that although only the equals alignment was
+excluded, the ternary alignments were also lost. This happens because the
+vertical aligner sweeps from left-to-right and usually stops if an important
+alignment cannot be made for some reason.
+
+But also notice that side comments remain aligned because their alignment is
+controlled separately with the parameter B<--valign-side_comments> described above.
+