+++ /dev/null
-.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" Set up some character translations and predefined strings. \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. \*(C+ will
-.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-. ds -- \(*W-
-. ds PI pi
-. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
-. ds L" ""
-. ds R" ""
-. ds C` ""
-. ds C' ""
-'br\}
-.el\{\
-. ds -- \|\(em\|
-. ds PI \(*p
-. ds L" ``
-. ds R" ''
-. ds C`
-. ds C'
-'br\}
-.\"
-.\" Escape single quotes in literal strings from groff's Unicode transform.
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
-.\" entries marked with X<> in POD. Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.\"
-.\" Avoid warning from groff about undefined register 'F'.
-.de IX
-..
-.nr rF 0
-.if \n(.g .if rF .nr rF 1
-.if (\n(rF:(\n(.g==0)) \{
-. if \nF \{
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
-..
-. if !\nF==2 \{
-. nr % 0
-. nr F 2
-. \}
-. \}
-.\}
-.rr rF
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear. Run. Save yourself. No user-serviceable parts.
-. \" fudge factors for nroff and troff
-.if n \{\
-. ds #H 0
-. ds #V .8m
-. ds #F .3m
-. ds #[ \f1
-. ds #] \fP
-.\}
-.if t \{\
-. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
-. ds #F 0
-. ds #[ \&
-. ds #] \&
-.\}
-. \" simple accents for nroff and troff
-.if n \{\
-. ds ' \&
-. ds ` \&
-. ds ^ \&
-. ds , \&
-. ds ~ ~
-. ds /
-.\}
-.if t \{\
-. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-. \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-. \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-. \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-. ds : e
-. ds 8 ss
-. ds o a
-. ds d- d\h'-1'\(ga
-. ds D- D\h'-1'\(hy
-. ds th \o'bp'
-. ds Th \o'LP'
-. ds ae ae
-. ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "PERLTIDY 1"
-.TH PERLTIDY 1 "2018-02-20" "perl v5.22.1" "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
-.nh
-.SH "NAME"
-perltidy \- a perl script indenter and reformatter
-.SH "SYNOPSIS"
-.IX Header "SYNOPSIS"
-.Vb 5
-\& perltidy [ options ] file1 file2 file3 ...
-\& (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
-\& perltidy [ options ] file1 \-o outfile
-\& perltidy [ options ] file1 \-st >outfile
-\& perltidy [ options ] <infile >outfile
-.Ve
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-Perltidy reads a perl script and writes an indented, reformatted script.
-.PP
-Many users will find enough information in \*(L"\s-1EXAMPLES\*(R"\s0 to get
-started. New users may benefit from the short tutorial
-which can be found at
-http://perltidy.sourceforge.net/tutorial.html
-.PP
-A convenient aid to systematically defining a set of style parameters
-can be found at
-http://perltidy.sourceforge.net/stylekey.html
-.PP
-Perltidy can produce output on either of two modes, depending on the
-existence of an \fB\-html\fR flag. Without this flag, the output is passed
-through a formatter. The default formatting tries to follow the
-recommendations in \fIperlstyle\fR\|(1), but it can be controlled in detail with
-numerous input parameters, which are described in \*(L"\s-1FORMATTING
-OPTIONS\*(R"\s0.
-.PP
-When the \fB\-html\fR flag is given, the output is passed through an \s-1HTML\s0
-formatter which is described in \*(L"\s-1HTML OPTIONS\*(R"\s0.
-.SH "EXAMPLES"
-.IX Header "EXAMPLES"
-.Vb 1
-\& perltidy somefile.pl
-.Ve
-.PP
-This will produce a file \fIsomefile.pl.tdy\fR containing the script reformatted
-using the default options, which approximate the style suggested in
-\&\fIperlstyle\fR\|(1). The source file \fIsomefile.pl\fR is unchanged.
-.PP
-.Vb 1
-\& perltidy *.pl
-.Ve
-.PP
-Execute perltidy on all \fI.pl\fR files in the current directory with the
-default options. The output will be in files with an appended \fI.tdy\fR
-extension. For any file with an error, there will be a file with extension
-\&\fI.ERR\fR.
-.PP
-.Vb 1
-\& perltidy \-b file1.pl file2.pl
-.Ve
-.PP
-Modify \fIfile1.pl\fR and \fIfile2.pl\fR in place, and backup the originals to
-\&\fIfile1.pl.bak\fR and \fIfile2.pl.bak\fR. If \fIfile1.pl.bak\fR and/or \fIfile2.pl.bak\fR
-already exist, they will be overwritten.
-.PP
-.Vb 1
-\& perltidy \-b \-bext=\*(Aq/\*(Aq file1.pl file2.pl
-.Ve
-.PP
-Same as the previous example except that the backup files \fIfile1.pl.bak\fR and \fIfile2.pl.bak\fR will be deleted if there are no errors.
-.PP
-.Vb 1
-\& perltidy \-gnu somefile.pl
-.Ve
-.PP
-Execute perltidy on file \fIsomefile.pl\fR with a style which approximates the
-\&\s-1GNU\s0 Coding Standards for C programs. The output will be \fIsomefile.pl.tdy\fR.
-.PP
-.Vb 1
-\& perltidy \-i=3 somefile.pl
-.Ve
-.PP
-Execute perltidy on file \fIsomefile.pl\fR, with 3 columns for each level of
-indentation (\fB\-i=3\fR) instead of the default 4 columns. There will not be any
-tabs in the reformatted script, except for any which already exist in comments,
-pod documents, quotes, and here documents. Output will be \fIsomefile.pl.tdy\fR.
-.PP
-.Vb 1
-\& perltidy \-i=3 \-et=8 somefile.pl
-.Ve
-.PP
-Same as the previous example, except that leading whitespace will
-be entabbed with one tab character per 8 spaces.
-.PP
-.Vb 1
-\& perltidy \-ce \-l=72 somefile.pl
-.Ve
-.PP
-Execute perltidy on file \fIsomefile.pl\fR with all defaults except use \*(L"cuddled
-elses\*(R" (\fB\-ce\fR) and a maximum line length of 72 columns (\fB\-l=72\fR) instead of
-the default 80 columns.
-.PP
-.Vb 1
-\& perltidy \-g somefile.pl
-.Ve
-.PP
-Execute perltidy on file \fIsomefile.pl\fR and save a log file \fIsomefile.pl.LOG\fR
-which shows the nesting of braces, parentheses, and square brackets at
-the start of every line.
-.PP
-.Vb 1
-\& perltidy \-html somefile.pl
-.Ve
-.PP
-This will produce a file \fIsomefile.pl.html\fR containing the script with
-html markup. The output file will contain an embedded style sheet in
-the <\s-1HEAD\s0> section which may be edited to change the appearance.
-.PP
-.Vb 1
-\& perltidy \-html \-css=mystyle.css somefile.pl
-.Ve
-.PP
-This will produce a file \fIsomefile.pl.html\fR containing the script with
-html markup. This output file will contain a link to a separate style
-sheet file \fImystyle.css\fR. If the file \fImystyle.css\fR does not exist,
-it will be created. If it exists, it will not be overwritten.
-.PP
-.Vb 1
-\& perltidy \-html \-pre somefile.pl
-.Ve
-.PP
-Write an html snippet with only the \s-1PRE\s0 section to \fIsomefile.pl.html\fR.
-This is useful when code snippets are being formatted for inclusion in a
-larger web page. No style sheet will be written in this case.
-.PP
-.Vb 1
-\& perltidy \-html \-ss >mystyle.css
-.Ve
-.PP
-Write a style sheet to \fImystyle.css\fR and exit.
-.PP
-.Vb 1
-\& perltidy \-html \-frm mymodule.pm
-.Ve
-.PP
-Write html with a frame holding a table of contents and the source code. The
-output files will be \fImymodule.pm.html\fR (the frame), \fImymodule.pm.toc.html\fR
-(the table of contents), and \fImymodule.pm.src.html\fR (the source code).
-.SH "OPTIONS \- OVERVIEW"
-.IX Header "OPTIONS - OVERVIEW"
-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.
-.PP
-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
-self-documenting and therefore useful in scripts. It is customary to
-use two leading dashes for long names, but one may be used.
-.PP
-Most parameters which serve as on/off flags can be negated with a
-leading \*(L"n\*(R" (for the short name) or a leading \*(L"no\*(R" or \*(L"no\-\*(R" (for the
-long name). For example, the flag to outdent long quotes is \fB\-olq\fR
-or \fB\-\-outdent\-long\-quotes\fR. The flag to skip this is \fB\-nolq\fR
-or \fB\-\-nooutdent\-long\-quotes\fR or \fB\-\-no\-outdent\-long\-quotes\fR.
-.PP
-Options may not be bundled together. In other words, options \fB\-q\fR and
-\&\fB\-g\fR may \s-1NOT\s0 be entered as \fB\-qg\fR.
-.PP
-Option names may be terminated early as long as they are uniquely identified.
-For example, instead of \fB\-\-dump\-token\-types\fR, it would be sufficient to enter
-\&\fB\-\-dump\-tok\fR, or even \fB\-\-dump\-t\fR, to uniquely identify this command.
-.SS "I/O control"
-.IX Subsection "I/O control"
-The following parameters concern the files which are read and written.
-.IP "\fB\-h\fR, \fB\-\-help\fR" 4
-.IX Item "-h, --help"
-Show summary of usage and exit.
-.IP "\fB\-o\fR=filename, \fB\-\-outfile\fR=filename" 4
-.IX Item "-o=filename, --outfile=filename"
-Name of the output file (only if a single input file is being
-processed). If no output file is specified, and output is not
-redirected to the standard output, the output will go to \fIfilename.tdy\fR.
-.IP "\fB\-st\fR, \fB\-\-standard\-output\fR" 4
-.IX Item "-st, --standard-output"
-Perltidy must be able to operate on an arbitrarily large number of files
-in a single run, with each output being directed to a different output
-file. Obviously this would conflict with outputting to the single
-standard output device, so a special flag, \fB\-st\fR, is required to
-request outputting to the standard output. For example,
-.Sp
-.Vb 1
-\& perltidy somefile.pl \-st >somefile.new.pl
-.Ve
-.Sp
-This option may only be used if there is just a single input file.
-The default is \fB\-nst\fR or \fB\-\-nostandard\-output\fR.
-.IP "\fB\-se\fR, \fB\-\-standard\-error\-output\fR" 4
-.IX Item "-se, --standard-error-output"
-If perltidy detects an error when processing file \fIsomefile.pl\fR, its
-default behavior is to write error messages to file \fIsomefile.pl.ERR\fR.
-Use \fB\-se\fR to cause all error messages to be sent to the standard error
-output stream instead. This directive may be negated with \fB\-nse\fR.
-Thus, you may place \fB\-se\fR in a \fI.perltidyrc\fR and override it when
-desired with \fB\-nse\fR on the command line.
-.IP "\fB\-oext\fR=ext, \fB\-\-output\-file\-extension\fR=ext" 4
-.IX Item "-oext=ext, --output-file-extension=ext"
-Change the extension of the output file to be \fIext\fR instead of the
-default \fItdy\fR (or \fIhtml\fR in case the \-\fB\-html\fR option is used).
-See \*(L"Specifying File Extensions\*(R".
-.IP "\fB\-opath\fR=path, \fB\-\-output\-path\fR=path" 4
-.IX Item "-opath=path, --output-path=path"
-When perltidy creates a filename for an output file, by default it merely
-appends an extension to the path and basename of the input file. This
-parameter causes the path to be changed to \fIpath\fR instead.
-.Sp
-The path should end in a valid path separator character, but perltidy will try
-to add one if it is missing.
-.Sp
-For example
-.Sp
-.Vb 1
-\& perltidy somefile.pl \-opath=/tmp/
-.Ve
-.Sp
-will produce \fI/tmp/somefile.pl.tdy\fR. Otherwise, \fIsomefile.pl.tdy\fR will
-appear in whatever directory contains \fIsomefile.pl\fR.
-.Sp
-If the path contains spaces, it should be placed in quotes.
-.Sp
-This parameter will be ignored if output is being directed to standard output,
-or if it is being specified explicitly with the \fB\-o=s\fR parameter.
-.IP "\fB\-b\fR, \fB\-\-backup\-and\-modify\-in\-place\fR" 4
-.IX Item "-b, --backup-and-modify-in-place"
-Modify the input file or files in-place and save the original with the
-extension \fI.bak\fR. Any existing \fI.bak\fR file will be deleted. See next
-item for changing the default backup extension, and for eliminating the
-backup file altogether.
-.Sp
-A \fB\-b\fR flag will be ignored if input is from standard input or goes to
-standard output, or if the \fB\-html\fR flag is set.
-.Sp
-In particular, if you want to use both the \fB\-b\fR flag and the \fB\-pbp\fR
-(\-\-perl\-best\-practices) flag, then you must put a \fB\-nst\fR flag after the
-\&\fB\-pbp\fR flag because it contains a \fB\-st\fR flag as one of its components,
-which means that output will go to the standard output stream.
-.IP "\fB\-bext\fR=ext, \fB\-\-backup\-file\-extension\fR=ext" 4
-.IX Item "-bext=ext, --backup-file-extension=ext"
-This parameter serves two purposes: (1) to change the extension of the backup
-file to be something other than the default \fI.bak\fR, and (2) to indicate
-that no backup file should be saved.
-.Sp
-To change the default extension to something other than \fI.bak\fR see
-\&\*(L"Specifying File Extensions\*(R".
-.Sp
-A backup file of the source is always written, but you can request that it
-be deleted at the end of processing if there were no errors. This is risky
-unless the source code is being maintained with a source code control
-system.
-.Sp
-To indicate that the backup should be deleted include one forward slash,
-\&\fB/\fR, in the extension. If any text remains after the slash is removed
-it will be used to define the backup file extension (which is always
-created and only deleted if there were no errors).
-.Sp
-Here are some examples:
-.Sp
-.Vb 5
-\& Parameter Extension Backup File Treatment
-\& <\-bext=bak> F<.bak> Keep (same as the default behavior)
-\& <\-bext=\*(Aq/\*(Aq> F<.bak> Delete if no errors
-\& <\-bext=\*(Aq/backup\*(Aq> F<.backup> Delete if no errors
-\& <\-bext=\*(Aqoriginal/\*(Aq> F<.original> Delete if no errors
-.Ve
-.IP "\fB\-w\fR, \fB\-\-warning\-output\fR" 4
-.IX Item "-w, --warning-output"
-Setting \fB\-w\fR causes any non-critical warning
-messages to be reported as errors. These include messages
-about possible pod problems, possibly bad starting indentation level,
-and cautions about indirect object usage. The default, \fB\-nw\fR or
-\&\fB\-\-nowarning\-output\fR, is not to include these warnings.
-.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
-.IX Item "-q, --quiet"
-Deactivate error messages and syntax checking (for running under
-an editor).
-.Sp
-For example, if you use a vi-style editor, such as vim, you may execute
-perltidy as a filter from within the editor using something like
-.Sp
-.Vb 1
-\& :n1,n2!perltidy \-q
-.Ve
-.Sp
-where \f(CW\*(C`n1,n2\*(C'\fR represents the selected text. Without the \fB\-q\fR flag,
-any error message may mess up your screen, so be prepared to use your
-\&\*(L"undo\*(R" key.
-.IP "\fB\-log\fR, \fB\-\-logfile\fR" 4
-.IX Item "-log, --logfile"
-Save the \fI.LOG\fR file, which has many useful diagnostics. Perltidy always
-creates a \fI.LOG\fR file, but by default it is deleted unless a program bug is
-suspected. Setting the \fB\-log\fR flag forces the log file to be saved.
-.IP "\fB\-g=n\fR, \fB\-\-logfile\-gap=n\fR" 4
-.IX Item "-g=n, --logfile-gap=n"
-Set maximum interval between input code lines in the logfile. This purpose of
-this flag is to assist in debugging nesting errors. The value of \f(CW\*(C`n\*(C'\fR is
-optional. If you set the flag \fB\-g\fR without the value of \f(CW\*(C`n\*(C'\fR, it will be
-taken to be 1, meaning that every line will be written to the log file. This
-can be helpful if you are looking for a brace, paren, or bracket nesting error.
-.Sp
-Setting \fB\-g\fR also causes the logfile to be saved, so it is not necessary to
-also include \fB\-log\fR.
-.Sp
-If no \fB\-g\fR flag is given, a value of 50 will be used, meaning that at least
-every 50th line will be recorded in the logfile. This helps prevent
-excessively long log files.
-.Sp
-Setting a negative value of \f(CW\*(C`n\*(C'\fR is the same as not setting \fB\-g\fR at all.
-.IP "\fB\-npro\fR \fB\-\-noprofile\fR" 4
-.IX Item "-npro --noprofile"
-Ignore any \fI.perltidyrc\fR command file. Normally, perltidy looks first in
-your current directory for a \fI.perltidyrc\fR file of parameters. (The format
-is described below). If it finds one, it applies those options to the
-initial default values, and then it applies any that have been defined
-on the command line. If no \fI.perltidyrc\fR file is found, it looks for one
-in your home directory.
-.Sp
-If you set the \fB\-npro\fR flag, perltidy will not look for this file.
-.IP "\fB\-pro=filename\fR or \fB\-\-profile=filename\fR" 4
-.IX Item "-pro=filename or --profile=filename"
-To simplify testing and switching .perltidyrc files, this command may be
-used to specify a configuration file which will override the default
-name of .perltidyrc. There must not be a space on either side of the
-\&'=' sign. For example, the line
-.Sp
-.Vb 1
-\& perltidy \-pro=testcfg
-.Ve
-.Sp
-would cause file \fItestcfg\fR to be used instead of the
-default \fI.perltidyrc\fR.
-.Sp
-A pathname begins with three dots, e.g. \*(L".../.perltidyrc\*(R", indicates that
-the file should be searched for starting in the current directory and
-working upwards. This makes it easier to have multiple projects each with
-their own .perltidyrc in their root directories.
-.IP "\fB\-opt\fR, \fB\-\-show\-options\fR" 4
-.IX Item "-opt, --show-options"
-Write a list of all options used to the \fI.LOG\fR file.
-Please see \fB\-\-dump\-options\fR for a simpler way to do this.
-.IP "\fB\-f\fR, \fB\-\-force\-read\-binary\fR" 4
-.IX Item "-f, --force-read-binary"
-Force perltidy to process binary files. To avoid producing excessive
-error messages, perltidy skips files identified by the system as non-text.
-However, valid perl scripts containing binary data may sometimes be identified
-as non-text, and this flag forces perltidy to process them.
-.SH "FORMATTING OPTIONS"
-.IX Header "FORMATTING OPTIONS"
-.SS "Basic Options"
-.IX Subsection "Basic Options"
-.IP "\fB\-\-notidy\fR" 4
-.IX Item "--notidy"
-This flag disables all formatting and causes the input to be copied unchanged
-to the output except for possible changes in line ending characters and any
-pre\- and post-filters. This can be useful in conjunction with a hierarchical
-set of \fI.perltidyrc\fR files to avoid unwanted code tidying. See also
-\&\*(L"Skipping Selected Sections of Code\*(R" for a way to avoid tidying specific
-sections of code.
-.IP "\fB\-i=n\fR, \fB\-\-indent\-columns=n\fR" 4
-.IX Item "-i=n, --indent-columns=n"
-Use n columns per indentation level (default n=4).
-.IP "\fB\-l=n\fR, \fB\-\-maximum\-line\-length=n\fR" 4
-.IX Item "-l=n, --maximum-line-length=n"
-The default maximum line length is n=80 characters. Perltidy will try
-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 \fB\-l=0\fR is equivalent to setting \fB\-l=(a large number)\fR.
-.IP "\fB\-vmll\fR, \fB\-\-variable\-maximum\-line\-length\fR" 4
-.IX Item "-vmll, --variable-maximum-line-length"
-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 \fB\-vmll\fR flag, which
-basically tells perltidy to ignore leading whitespace when measuring the line
-length.
-.Sp
-To be precise, when the \fB\-vmll\fR parameter is set, the maximum line length of a
-line of code will be M+L*I, where
-.Sp
-.Vb 3
-\& 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
-.Ve
-.Sp
-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.
-.Sp
-The default is not to do this (\fB\-nvmll\fR).
-.IP "\fB\-wc=n\fR, \fB\-\-whitespace\-cycle=n\fR" 4
-.IX Item "-wc=n, --whitespace-cycle=n"
-This flag also addresses problems with very deeply nested code and data
-structures. When the nesting depth exceeds the value \fBn\fR 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.
-.Sp
-For example if one level of indentation equals 4 spaces (\fB\-i=4\fR, the default),
-and one uses \fB\-wc=15\fR, 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.
-.Sp
-The combination of \fB\-vmll\fR and \fB\-wc=n\fR provides a solution to the problem of
-displaying arbitrarily deep data structures and code in a finite window,
-although \fB\-wc=n\fR may of course be used without \fB\-vmll\fR.
-.Sp
-The default is not to use this, which can also be indicated using \fB\-wc=0\fR.
-.IP "tabs" 4
-.IX Item "tabs"
-Using tab characters will almost certainly lead to future portability
-and maintenance problems, so the default and recommendation is not to
-use them. For those who prefer tabs, however, there are two different
-options.
-.Sp
-Except for possibly introducing tab indentation characters, as outlined
-below, perltidy does not introduce any tab characters into your file,
-and it removes any tabs from the code (unless requested not to do so
-with \fB\-fws\fR). If you have any tabs in your comments, quotes, or
-here-documents, they will remain.
-.RS 4
-.IP "\fB\-et=n\fR, \fB\-\-entab\-leading\-whitespace\fR" 4
-.IX Item "-et=n, --entab-leading-whitespace"
-This flag causes each \fBn\fR initial space characters to be replaced by
-one tab character. Note that the integer \fBn\fR is completely independent
-of the integer specified for indentation parameter, \fB\-i=n\fR.
-.IP "\fB\-t\fR, \fB\-\-tabs\fR" 4
-.IX Item "-t, --tabs"
-This flag causes one leading tab character to be inserted for each level
-of indentation. Certain other features are incompatible with this
-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 \fB\-lp\fR
-option.
-.IP "\fB\-dt=n\fR, \fB\-\-default\-tabsize=n\fR" 4
-.IX Item "-dt=n, --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 \fBn\fR
-corresponding to each leading tab of the input stream may be specified with
-\&\fB\-dt=n\fR. The default is \fBn=8\fR.
-.Sp
-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).
-.RE
-.RS 4
-.RE
-.IP "\fB\-syn\fR, \fB\-\-check\-syntax\fR" 4
-.IX Item "-syn, --check-syntax"
-This flag is now ignored for safety, but the following documentation
-has been retained for reference.
-.Sp
-This flag causes perltidy to run \f(CW\*(C`perl \-c \-T\*(C'\fR to check syntax of input
-and output. (To change the flags passed to perl, see the next
-item, \fB\-pscf\fR). The results are written to the \fI.LOG\fR file, which
-will be saved if an error is detected in the output script. The output
-script is not checked if the input script has a syntax error. Perltidy
-does its own checking, but this option employs perl to get a \*(L"second
-opinion\*(R".
-.Sp
-If perl reports errors in the input file, they will not be reported in
-the error output unless the \fB\-\-warning\-output\fR flag is given.
-.Sp
-The default is \fB\s-1NOT\s0\fR to do this type of syntax checking (although
-perltidy will still do as much self-checking as possible). The reason
-is that it causes all code in \s-1BEGIN\s0 blocks to be executed, for all
-modules being used, and this opens the door to security issues and
-infinite loops when running perltidy.
-.IP "\fB\-pscf=s\fR, \fB\-perl\-syntax\-check\-flags=s\fR" 4
-.IX Item "-pscf=s, -perl-syntax-check-flags=s"
-When perl is invoked to check syntax, the normal flags are \f(CW\*(C`\-c \-T\*(C'\fR. In
-addition, if the \fB\-x\fR flag is given to perltidy, then perl will also be
-passed a \fB\-x\fR flag. It should not normally be necessary to change
-these flags, but it can be done with the \fB\-pscf=s\fR flag. For example,
-if the taint flag, \f(CW\*(C`\-T\*(C'\fR, is not wanted, the flag could be set to be just
-\&\fB\-pscf=\-c\fR.
-.Sp
-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 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 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.
-(This also speeds up perltidy by well over a factor of two, so it might be
-useful when perltidy is merely being used to help find a brace error in
-a large script).
-.Sp
-Setting this flag is equivalent to setting \fB\-\-freeze\-newlines\fR and
-\&\fB\-\-freeze\-whitespace\fR.
-.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
-to output line endings for a specific system. Normally,
-perltidy writes files with the line separator character of the host
-system. The \f(CW\*(C`win\*(C'\fR and \f(CW\*(C`dos\*(C'\fR flags have an identical result.
-.IP "\fB\-ple\fR, \fB\-\-preserve\-line\-endings\fR" 4
-.IX Item "-ple, --preserve-line-endings"
-This flag tells perltidy to write its output files with the same line
-endings as the input file, if possible. It should work for
-\&\fBdos\fR, \fBunix\fR, and \fBmac\fR line endings. It will only work if perltidy
-input comes from a filename (rather than stdin, for example). If
-perltidy has trouble determining the input file line ending, it will
-revert to the default behavior of using the line ending of the host system.
-.IP "\fB\-it=n\fR, \fB\-\-iterations=n\fR" 4
-.IX Item "-it=n, --iterations=n"
-This flag causes perltidy to do \fBn\fR complete iterations. The reason for this
-flag is that code beautification is an iterative process and in some
-cases the output from perltidy can be different if it is applied a second time.
-For most purposes the default of \fBn=1\fR should be satisfactory. However \fBn=2\fR
-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
-\&\fBn\fR 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. See
-the next item for a simplified iteration control.
-.Sp
-This flag has no effect when perltidy is used to generate html.
-.IP "\fB\-conv\fR, \fB\-\-converge\fR" 4
-.IX Item "-conv, --converge"
-This flag is equivalent to \fB\-it=4\fR 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 \fB\-nconv\fR (no convergence check). Using
-\&\fB\-conv\fR will approximately double run time since normally one extra iteration
-is required to verify convergence.
-.SS "Code Indentation Control"
-.IX Subsection "Code Indentation Control"
-.IP "\fB\-ci=n\fR, \fB\-\-continuation\-indentation=n\fR" 4
-.IX Item "-ci=n, --continuation-indentation=n"
-Continuation indentation is extra indentation spaces applied when
-a long line is broken. The default is n=2, illustrated here:
-.Sp
-.Vb 2
-\& my $level = # \-ci=2
-\& ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
-.Ve
-.Sp
-The same example, with n=0, is a little harder to read:
-.Sp
-.Vb 2
-\& my $level = # \-ci=0
-\& ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
-.Ve
-.Sp
-The value given to \fB\-ci\fR is also used by some commands when a small
-space is required. Examples are commands for outdenting labels,
-\&\fB\-ola\fR, and control keywords, \fB\-okw\fR.
-.Sp
-When default values are not used, it is suggested that the value \fBn\fR
-given with \fB\-ci=n\fR be no more than about one-half of the number of
-spaces assigned to a full indentation level on the \fB\-i=n\fR command.
-.IP "\fB\-sil=n\fR \fB\-\-starting\-indentation\-level=n\fR" 4
-.IX Item "-sil=n --starting-indentation-level=n"
-By default, perltidy examines the input file and tries to determine the
-starting indentation level. While it is often zero, it may not be
-zero for a code snippet being sent from an editing session.
-.Sp
-To guess the starting indentation level perltidy simply assumes that
-indentation scheme used to create the code snippet is the same as is being used
-for the current perltidy process. This is the only sensible guess that can be
-made. It should be correct if this is true, but otherwise it probably won't.
-For example, if the input script was written with \-i=2 and the current peltidy
-flags have \-i=4, the wrong initial indentation will be guessed for a code
-snippet which has non-zero initial indentation. Likewise, if an entabbing
-scheme is used in the input script and not in the current process then the
-guessed indentation will be wrong.
-.Sp
-If the default method does not work correctly, or you want to change the
-starting level, use \fB\-sil=n\fR, to force the starting level to be n.
-.IP "List indentation using \fB\-lp\fR, \fB\-\-line\-up\-parentheses\fR" 4
-.IX Item "List indentation using -lp, --line-up-parentheses"
-By default, perltidy indents lists with 4 spaces, or whatever value
-is specified with \fB\-i=n\fR. Here is a small list formatted in this way:
-.Sp
-.Vb 5
-\& # perltidy (default)
-\& @month_of_year = (
-\& \*(AqJan\*(Aq, \*(AqFeb\*(Aq, \*(AqMar\*(Aq, \*(AqApr\*(Aq, \*(AqMay\*(Aq, \*(AqJun\*(Aq,
-\& \*(AqJul\*(Aq, \*(AqAug\*(Aq, \*(AqSep\*(Aq, \*(AqOct\*(Aq, \*(AqNov\*(Aq, \*(AqDec\*(Aq
-\& );
-.Ve
-.Sp
-Use the \fB\-lp\fR flag to add extra indentation to cause the data to begin
-past the opening parentheses of a sub call or list, or opening square
-bracket of an anonymous array, or opening curly brace of an anonymous
-hash. With this option, the above list would become:
-.Sp
-.Vb 5
-\& # perltidy \-lp
-\& @month_of_year = (
-\& \*(AqJan\*(Aq, \*(AqFeb\*(Aq, \*(AqMar\*(Aq, \*(AqApr\*(Aq, \*(AqMay\*(Aq, \*(AqJun\*(Aq,
-\& \*(AqJul\*(Aq, \*(AqAug\*(Aq, \*(AqSep\*(Aq, \*(AqOct\*(Aq, \*(AqNov\*(Aq, \*(AqDec\*(Aq
-\& );
-.Ve
-.Sp
-If the available line length (see \fB\-l=n\fR ) does not permit this much
-space, perltidy will use less. For alternate placement of the
-closing paren, see the next section.
-.Sp
-This option has no effect on code \s-1BLOCKS,\s0 such as if/then/else blocks,
-which always use whatever is specified with \fB\-i=n\fR. Also, the
-existence of line breaks and/or block comments between the opening and
-closing parens may cause perltidy to temporarily revert to its default
-method.
-.Sp
-Note: The \fB\-lp\fR option may not be used together with the \fB\-t\fR tabs option.
-It may, however, be used with the \fB\-et=n\fR tab method.
-.Sp
-In addition, any parameter which significantly restricts the ability of
-perltidy to choose newlines will conflict with \fB\-lp\fR and will cause
-\&\fB\-lp\fR to be deactivated. These include \fB\-io\fR, \fB\-fnl\fR, \fB\-nanl\fR, and
-\&\fB\-ndnl\fR. The reason is that the \fB\-lp\fR indentation style can require
-the careful coordination of an arbitrary number of break points in
-hierarchical lists, and these flags may prevent that.
-.IP "\fB\-cti=n\fR, \fB\-\-closing\-token\-indentation\fR" 4
-.IX Item "-cti=n, --closing-token-indentation"
-The \fB\-cti=n\fR flag controls the indentation of a line beginning with
-a \f(CW\*(C`)\*(C'\fR, \f(CW\*(C`]\*(C'\fR, or a non-block \f(CW\*(C`}\*(C'\fR. Such a line receives:
-.Sp
-.Vb 6
-\& \-cti = 0 no extra indentation (default)
-\& \-cti = 1 extra indentation such that the closing token
-\& aligns with its opening token.
-\& \-cti = 2 one extra indentation level if the line looks like:
-\& ); or ]; or };
-\& \-cti = 3 one extra indentation level always
-.Ve
-.Sp
-The flags \fB\-cti=1\fR and \fB\-cti=2\fR work well with the \fB\-lp\fR flag (previous
-section).
-.Sp
-.Vb 5
-\& # perltidy \-lp \-cti=1
-\& @month_of_year = (
-\& \*(AqJan\*(Aq, \*(AqFeb\*(Aq, \*(AqMar\*(Aq, \*(AqApr\*(Aq, \*(AqMay\*(Aq, \*(AqJun\*(Aq,
-\& \*(AqJul\*(Aq, \*(AqAug\*(Aq, \*(AqSep\*(Aq, \*(AqOct\*(Aq, \*(AqNov\*(Aq, \*(AqDec\*(Aq
-\& );
-\&
-\& # perltidy \-lp \-cti=2
-\& @month_of_year = (
-\& \*(AqJan\*(Aq, \*(AqFeb\*(Aq, \*(AqMar\*(Aq, \*(AqApr\*(Aq, \*(AqMay\*(Aq, \*(AqJun\*(Aq,
-\& \*(AqJul\*(Aq, \*(AqAug\*(Aq, \*(AqSep\*(Aq, \*(AqOct\*(Aq, \*(AqNov\*(Aq, \*(AqDec\*(Aq
-\& );
-.Ve
-.Sp
-These flags are merely hints to the formatter and they may not always be
-followed. In particular, if \-lp is not being used, the indentation for
-\&\fBcti=1\fR is constrained to be no more than one indentation level.
-.Sp
-If desired, this control can be applied independently to each of the
-closing container token types. In fact, \fB\-cti=n\fR is merely an
-abbreviation for \fB\-cpi=n \-csbi=n \-cbi=n\fR, where:
-\&\fB\-cpi\fR or \fB\-\-closing\-paren\-indentation\fR controls \fB)\fR's,
-\&\fB\-csbi\fR or \fB\-\-closing\-square\-bracket\-indentation\fR controls \fB]\fR's,
-\&\fB\-cbi\fR or \fB\-\-closing\-brace\-indentation\fR controls non-block \fB}\fR's.
-.IP "\fB\-icp\fR, \fB\-\-indent\-closing\-paren\fR" 4
-.IX Item "-icp, --indent-closing-paren"
-The \fB\-icp\fR flag is equivalent to
-\&\fB\-cti=2\fR, described in the previous section. The \fB\-nicp\fR flag is
-equivalent \fB\-cti=0\fR. They are included for backwards compatibility.
-.IP "\fB\-icb\fR, \fB\-\-indent\-closing\-brace\fR" 4
-.IX Item "-icb, --indent-closing-brace"
-The \fB\-icb\fR option gives one extra level of indentation to a brace which
-terminates a code block . For example,
-.Sp
-.Vb 6
-\& if ($task) {
-\& yyy();
-\& } # \-icb
-\& else {
-\& zzz();
-\& }
-.Ve
-.Sp
-The default is not to do this, indicated by \fB\-nicb\fR.
-.IP "\fB\-olq\fR, \fB\-\-outdent\-long\-quotes\fR" 4
-.IX Item "-olq, --outdent-long-quotes"
-When \fB\-olq\fR is set, lines which is a quoted string longer than the
-value \fBmaximum-line-length\fR will have their indentation removed to make
-them more readable. This is the default. To prevent such out-denting,
-use \fB\-nolq\fR or \fB\-\-nooutdent\-long\-lines\fR.
-.IP "\fB\-oll\fR, \fB\-\-outdent\-long\-lines\fR" 4
-.IX Item "-oll, --outdent-long-lines"
-This command is equivalent to \fB\-\-outdent\-long\-quotes\fR and
-\&\fB\-\-outdent\-long\-comments\fR, and it is included for compatibility with previous
-versions of perltidy. The negation of this also works, \fB\-noll\fR or
-\&\fB\-\-nooutdent\-long\-lines\fR, and is equivalent to setting \fB\-nolq\fR and \fB\-nolc\fR.
-.IP "Outdenting Labels: \fB\-ola\fR, \fB\-\-outdent\-labels\fR" 4
-.IX Item "Outdenting Labels: -ola, --outdent-labels"
-This command will cause labels to be outdented by 2 spaces (or whatever \fB\-ci\fR
-has been set to), if possible. This is the default. For example:
-.Sp
-.Vb 6
-\& my $i;
-\& LOOP: while ( $i = <FOTOS> ) {
-\& chomp($i);
-\& next unless $i;
-\& fixit($i);
-\& }
-.Ve
-.Sp
-Use \fB\-nola\fR to not outdent labels.
-.IP "Outdenting Keywords" 4
-.IX Item "Outdenting Keywords"
-.RS 4
-.PD 0
-.IP "\fB\-okw\fR, \fB\-\-outdent\-keywords\fR" 4
-.IX Item "-okw, --outdent-keywords"
-.PD
-The command \fB\-okw\fR will cause certain leading control keywords to
-be outdented by 2 spaces (or whatever \fB\-ci\fR has been set to), if
-possible. By default, these keywords are \f(CW\*(C`redo\*(C'\fR, \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR,
-\&\f(CW\*(C`goto\*(C'\fR, and \f(CW\*(C`return\*(C'\fR. The intention is to make these control keywords
-easier to see. To change this list of keywords being outdented, see
-the next section.
-.Sp
-For example, using \f(CW\*(C`perltidy \-okw\*(C'\fR on the previous example gives:
-.Sp
-.Vb 6
-\& my $i;
-\& LOOP: while ( $i = <FOTOS> ) {
-\& chomp($i);
-\& next unless $i;
-\& fixit($i);
-\& }
-.Ve
-.Sp
-The default is not to do this.
-.IP "Specifying Outdented Keywords: \fB\-okwl=string\fR, \fB\-\-outdent\-keyword\-list=string\fR" 4
-.IX Item "Specifying Outdented Keywords: -okwl=string, --outdent-keyword-list=string"
-This command can be used to change the keywords which are outdented with
-the \fB\-okw\fR command. The parameter \fBstring\fR is a required list of perl
-keywords, which should be placed in quotes if there are more than one.
-By itself, it does not cause any outdenting to occur, so the \fB\-okw\fR
-command is still required.
-.Sp
-For example, the commands \f(CW\*(C`\-okwl="next last redo goto" \-okw\*(C'\fR will cause
-those four keywords to be outdented. It is probably simplest to place
-any \fB\-okwl\fR command in a \fI.perltidyrc\fR file.
-.RE
-.RS 4
-.RE
-.SS "Whitespace Control"
-.IX Subsection "Whitespace Control"
-Whitespace refers to the blank space between variables, operators,
-and other code tokens.
-.IP "\fB\-fws\fR, \fB\-\-freeze\-whitespace\fR" 4
-.IX Item "-fws, --freeze-whitespace"
-This flag causes your original whitespace to remain unchanged, and
-causes the rest of the whitespace commands in this section, the
-Code Indentation section, and
-the Comment Control section to be ignored.
-.IP "Tightness of curly braces, parentheses, and square brackets." 4
-.IX Item "Tightness of curly braces, parentheses, and square brackets."
-Here the term \*(L"tightness\*(R" will mean the closeness with which
-pairs of enclosing tokens, such as parentheses, contain the quantities
-within. A numerical value of 0, 1, or 2 defines the tightness, with
-0 being least tight and 2 being most tight. Spaces within containers
-are always symmetric, so if there is a space after a \f(CW\*(C`(\*(C'\fR then there
-will be a space before the corresponding \f(CW\*(C`)\*(C'\fR.
-.Sp
-The \fB\-pt=n\fR or \fB\-\-paren\-tightness=n\fR parameter controls the space within
-parens. The example below shows the effect of the three possible
-values, 0, 1, and 2:
-.Sp
-.Vb 3
-\& if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # \-pt=0
-\& if ( ( my $len_tab = length($tabstr) ) > 0 ) { # \-pt=1 (default)
-\& if ((my $len_tab = length($tabstr)) > 0) { # \-pt=2
-.Ve
-.Sp
-When n is 0, there is always a space to the right of a '(' and to the left
-of a ')'. For n=2 there is never a space. For n=1, the default, there
-is a space unless the quantity within the parens is a single token, such
-as an identifier or quoted string.
-.Sp
-Likewise, the parameter \fB\-sbt=n\fR or \fB\-\-square\-bracket\-tightness=n\fR
-controls the space within square brackets, as illustrated below.
-.Sp
-.Vb 3
-\& $width = $col[ $j + $k ] \- $col[ $j ]; # \-sbt=0
-\& $width = $col[ $j + $k ] \- $col[$j]; # \-sbt=1 (default)
-\& $width = $col[$j + $k] \- $col[$j]; # \-sbt=2
-.Ve
-.Sp
-Curly braces which do not contain code blocks are controlled by
-the parameter \fB\-bt=n\fR or \fB\-\-brace\-tightness=n\fR.
-.Sp
-.Vb 3
-\& $obj\->{ $parsed_sql\->{ \*(Aqtable\*(Aq }[0] }; # \-bt=0
-\& $obj\->{ $parsed_sql\->{\*(Aqtable\*(Aq}[0] }; # \-bt=1 (default)
-\& $obj\->{$parsed_sql\->{\*(Aqtable\*(Aq}[0]}; # \-bt=2
-.Ve
-.Sp
-And finally, curly braces which contain blocks of code are controlled by the
-parameter \fB\-bbt=n\fR or \fB\-\-block\-brace\-tightness=n\fR as illustrated in the
-example below.
-.Sp
-.Vb 3
-\& %bf = map { $_ => \-M $_ } grep { /\e.deb$/ } dirents \*(Aq.\*(Aq; # \-bbt=0 (default)
-\& %bf = map { $_ => \-M $_ } grep {/\e.deb$/} dirents \*(Aq.\*(Aq; # \-bbt=1
-\& %bf = map {$_ => \-M $_} grep {/\e.deb$/} dirents \*(Aq.\*(Aq; # \-bbt=2
-.Ve
-.Sp
-To simplify input in the case that all of the tightness flags have the same
-value <n>, the parameter <\-act=n> or \fB\-\-all\-containers\-tightness=n\fR is an
-abbreviation for the combination <\-pt=n \-sbt=n \-bt=n \-bbt=n>.
-.IP "\fB\-tso\fR, \fB\-\-tight\-secret\-operators\fR" 4
-.IX Item "-tso, --tight-secret-operators"
-The flag \fB\-tso\fR causes certain perl token sequences (secret operators)
-which might be considered to be a single operator to be formatted \*(L"tightly\*(R"
-(without spaces). The operators currently modified by this flag are:
-.Sp
-.Vb 1
-\& 0+ +0 ()x!! ~~<> ,=> =( )=
-.Ve
-.Sp
-For example the sequence \fB0 +\fR, which converts a string to a number,
-would be formatted without a space: \fB0+\fR when the \fB\-tso\fR flag is set. This
-flag is off by default.
-.IP "\fB\-sts\fR, \fB\-\-space\-terminal\-semicolon\fR" 4
-.IX Item "-sts, --space-terminal-semicolon"
-Some programmers prefer a space before all terminal semicolons. The
-default is for no such space, and is indicated with \fB\-nsts\fR or
-\&\fB\-\-nospace\-terminal\-semicolon\fR.
-.Sp
-.Vb 2
-\& $i = 1 ; # \-sts
-\& $i = 1; # \-nsts (default)
-.Ve
-.IP "\fB\-sfs\fR, \fB\-\-space\-for\-semicolon\fR" 4
-.IX Item "-sfs, --space-for-semicolon"
-Semicolons within \fBfor\fR loops may sometimes be hard to see,
-particularly when commas are also present. This option places spaces on
-both sides of these special semicolons, and is the default. Use
-\&\fB\-nsfs\fR or \fB\-\-nospace\-for\-semicolon\fR to deactivate it.
-.Sp
-.Vb 2
-\& for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # \-sfs (default)
-\& for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # \-nsfs
-.Ve
-.IP "\fB\-asc\fR, \fB\-\-add\-semicolons\fR" 4
-.IX Item "-asc, --add-semicolons"
-Setting \fB\-asc\fR allows perltidy to add any missing optional semicolon at the end
-of a line which is followed by a closing curly brace on the next line. This
-is the default, and may be deactivated with \fB\-nasc\fR or \fB\-\-noadd\-semicolons\fR.
-.IP "\fB\-dsm\fR, \fB\-\-delete\-semicolons\fR" 4
-.IX Item "-dsm, --delete-semicolons"
-Setting \fB\-dsm\fR allows perltidy to delete extra semicolons which are
-simply empty statements. This is the default, and may be deactivated
-with \fB\-ndsm\fR or \fB\-\-nodelete\-semicolons\fR. (Such semicolons are not
-deleted, however, if they would promote a side comment to a block
-comment).
-.IP "\fB\-aws\fR, \fB\-\-add\-whitespace\fR" 4
-.IX Item "-aws, --add-whitespace"
-Setting this option allows perltidy to add certain whitespace improve
-code readability. This is the default. If you do not want any
-whitespace added, but are willing to have some whitespace deleted, use
-\&\fB\-naws\fR. (Use \fB\-fws\fR to leave whitespace completely unchanged).
-.IP "\fB\-dws\fR, \fB\-\-delete\-old\-whitespace\fR" 4
-.IX Item "-dws, --delete-old-whitespace"
-Setting this option allows perltidy to remove some old whitespace
-between characters, if necessary. This is the default. If you
-do not want any old whitespace removed, use \fB\-ndws\fR or
-\&\fB\-\-nodelete\-old\-whitespace\fR.
-.IP "Detailed whitespace controls around tokens" 4
-.IX Item "Detailed whitespace controls around tokens"
-For those who want more detailed control over the whitespace around
-tokens, there are four parameters which can directly modify the default
-whitespace rules built into perltidy for any token. They are:
-.Sp
-\&\fB\-wls=s\fR or \fB\-\-want\-left\-space=s\fR,
-.Sp
-\&\fB\-nwls=s\fR or \fB\-\-nowant\-left\-space=s\fR,
-.Sp
-\&\fB\-wrs=s\fR or \fB\-\-want\-right\-space=s\fR,
-.Sp
-\&\fB\-nwrs=s\fR or \fB\-\-nowant\-right\-space=s\fR.
-.Sp
-These parameters are each followed by a quoted string, \fBs\fR, containing a
-list of token types. No more than one of each of these parameters
-should be specified, because repeating a command-line parameter
-always overwrites the previous one before perltidy ever sees it.
-.Sp
-To illustrate how these are used, suppose it is desired that there be no
-space on either side of the token types \fB= + \- / *\fR. The following two
-parameters would specify this desire:
-.Sp
-.Vb 1
-\& \-nwls="= + \- / *" \-nwrs="= + \- / *"
-.Ve
-.Sp
-(Note that the token types are in quotes, and that they are separated by
-spaces). With these modified whitespace rules, the following line of math:
-.Sp
-.Vb 1
-\& $root = \-$b + sqrt( $b * $b \- 4. * $a * $c ) / ( 2. * $a );
-.Ve
-.Sp
-becomes this:
-.Sp
-.Vb 1
-\& $root=\-$b+sqrt( $b*$b\-4.*$a*$c )/( 2.*$a );
-.Ve
-.Sp
-These parameters should be considered to be hints to perltidy rather
-than fixed rules, because perltidy must try to resolve conflicts that
-arise between them and all of the other rules that it uses. One
-conflict that can arise is if, between two tokens, the left token wants
-a space and the right one doesn't. In this case, the token not wanting
-a space takes priority.
-.Sp
-It is necessary to have a list of all token types in order to create
-this type of input. Such a list can be obtained by the command
-\&\fB\-\-dump\-token\-types\fR. Also try the \fB\-D\fR flag on a short snippet of code
-and look at the .DEBUG file to see the tokenization.
-.Sp
-\&\fB\s-1WARNING\s0\fR Be sure to put these tokens in quotes to avoid having them
-misinterpreted by your command shell.
-.IP "Space between specific keywords and opening paren" 4
-.IX Item "Space between specific keywords and opening paren"
-When an opening paren follows a Perl keyword, no space is introduced after the
-keyword, unless it is (by default) one of these:
-.Sp
-.Vb 2
-\& my local our and or eq ne if else elsif until unless
-\& while for foreach return switch case given when
-.Ve
-.Sp
-These defaults can be modified with two commands:
-.Sp
-\&\fB\-sak=s\fR or \fB\-\-space\-after\-keyword=s\fR adds keywords.
-.Sp
-\&\fB\-nsak=s\fR or \fB\-\-nospace\-after\-keyword=s\fR removes keywords.
-.Sp
-where \fBs\fR is a list of keywords (in quotes if necessary). For example,
-.Sp
-.Vb 2
-\& my ( $a, $b, $c ) = @_; # default
-\& my( $a, $b, $c ) = @_; # \-nsak="my local our"
-.Ve
-.Sp
-The abbreviation \fB\-nsak='*'\fR is equivalent to including all of the
-keywords in the above list.
-.Sp
-When both \fB\-nsak=s\fR and \fB\-sak=s\fR commands are included, the \fB\-nsak=s\fR
-command is executed first. For example, to have space after only the
-keywords (my, local, our) you could use \fB\-nsak=\*(L"*\*(R" \-sak=\*(L"my local our\*(R"\fR.
-.Sp
-To put a space after all keywords, see the next item.
-.IP "Space between all keywords and opening parens" 4
-.IX Item "Space between all keywords and opening parens"
-When an opening paren follows a function or keyword, no space is introduced
-after the keyword except for the keywords noted in the previous item. To
-always put a space between a function or keyword and its opening paren,
-use the command:
-.Sp
-\&\fB\-skp\fR or \fB\-\-space\-keyword\-paren\fR
-.Sp
-You will probably also want to use the flag \fB\-sfp\fR (next item) too.
-.IP "Space between all function names and opening parens" 4
-.IX Item "Space between all function names and opening parens"
-When an opening paren follows a function the default is not to introduce
-a space. To cause a space to be introduced use:
-.Sp
-\&\fB\-sfp\fR or \fB\-\-space\-function\-paren\fR
-.Sp
-.Vb 2
-\& myfunc( $a, $b, $c ); # default
-\& myfunc ( $a, $b, $c ); # \-sfp
-.Ve
-.Sp
-You will probably also want to use the flag \fB\-skp\fR (previous item) too.
-.ie n .IP "Trimming whitespace around ""qw"" quotes" 4
-.el .IP "Trimming whitespace around \f(CWqw\fR quotes" 4
-.IX Item "Trimming whitespace around qw quotes"
-\&\fB\-tqw\fR or \fB\-\-trim\-qw\fR provide the default behavior of trimming
-spaces around multi-line \f(CW\*(C`qw\*(C'\fR quotes and indenting them appropriately.
-.Sp
-\&\fB\-ntqw\fR or \fB\-\-notrim\-qw\fR cause leading and trailing whitespace around
-multi-line \f(CW\*(C`qw\*(C'\fR 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 \f(CW\*(C`qw\*(C'\fR quotes changes the syntax tree.
-.IP "\fB\-sbq=n\fR or \fB\-\-space\-backslash\-quote=n\fR" 4
-.IX Item "-sbq=n or --space-backslash-quote=n"
-Lines like
-.Sp
-.Vb 2
-\& $str1=\e"string1";
-\& $str2=\e\*(Aqstring2\*(Aq;
-.Ve
-.Sp
-can confuse syntax highlighters unless a space is included between the backslash and the single or double quotation mark.
-.Sp
-This can be controlled with the value of \fBn\fR as follows:
-.Sp
-.Vb 3
-\& \-sbq=0 means no space between the backslash and quote
-\& \-sbq=1 means follow the example of the source code
-\& \-sbq=2 means always put a space between the backslash and quote
-.Ve
-.Sp
-The default is \fB\-sbq=1\fR, meaning that a space will be used 0if there is one in the source code.
-.IP "Trimming trailing whitespace from lines of \s-1POD\s0" 4
-.IX Item "Trimming trailing whitespace from lines of POD"
-\&\fB\-trp\fR or \fB\-\-trim\-pod\fR will remove trailing whitespace from lines of \s-1POD.\s0
-The default is not to do this.
-.SS "Comment Controls"
-.IX Subsection "Comment Controls"
-Perltidy has a number of ways to control the appearance of both block comments
-and side comments. The term \fBblock comment\fR here refers to a full-line
-comment, whereas \fBside comment\fR will refer to a comment which appears on a
-line to the right of some code.
-.IP "\fB\-ibc\fR, \fB\-\-indent\-block\-comments\fR" 4
-.IX Item "-ibc, --indent-block-comments"
-Block comments normally look best when they are indented to the same
-level as the code which follows them. This is the default behavior, but
-you may use \fB\-nibc\fR to keep block comments left-justified. Here is an
-example:
-.Sp
-.Vb 2
-\& # this comment is indented (\-ibc, default)
-\& if ($task) { yyy(); }
-.Ve
-.Sp
-The alternative is \fB\-nibc\fR:
-.Sp
-.Vb 2
-\& # this comment is not indented (\-nibc)
-\& if ($task) { yyy(); }
-.Ve
-.Sp
-See also the next item, \fB\-isbc\fR, as well as \fB\-sbc\fR, for other ways to
-have some indented and some outdented block comments.
-.IP "\fB\-isbc\fR, \fB\-\-indent\-spaced\-block\-comments\fR" 4
-.IX Item "-isbc, --indent-spaced-block-comments"
-If there is no leading space on the line, then the comment will not be
-indented, and otherwise it may be.
-.Sp
-If both \fB\-ibc\fR and \fB\-isbc\fR are set, then \fB\-isbc\fR takes priority.
-.IP "\fB\-olc\fR, \fB\-\-outdent\-long\-comments\fR" 4
-.IX Item "-olc, --outdent-long-comments"
-When \fB\-olc\fR is set, lines which are full-line (block) comments longer
-than the value \fBmaximum-line-length\fR will have their indentation
-removed. This is the default; use \fB\-nolc\fR to prevent outdenting.
-.IP "\fB\-msc=n\fR, \fB\-\-minimum\-space\-to\-comment=n\fR" 4
-.IX Item "-msc=n, --minimum-space-to-comment=n"
-Side comments look best when lined up several spaces to the right of
-code. Perltidy will try to keep comments at least n spaces to the
-right. The default is n=4 spaces.
-.IP "\fB\-fpsc=n\fR, \fB\-\-fixed\-position\-side\-comment=n\fR" 4
-.IX Item "-fpsc=n, --fixed-position-side-comment=n"
-This parameter tells perltidy to line up side comments in column number \fBn\fR
-whenever possible. The default, n=0, will not do this.
-.IP "\fB\-iscl\fR, \fB\-\-ignore\-side\-comment\-lengths\fR" 4
-.IX Item "-iscl, --ignore-side-comment-lengths"
-This parameter causes perltidy to ignore the length of side comments when
-setting line breaks. The default, \fB\-niscl\fR, is to include the length of
-side comments when breaking lines to stay within the length prescribed
-by the \fB\-l=n\fR maximum line length parameter. For example, the following
-long single line would remain intact with \-l=80 and \-iscl:
-.Sp
-.Vb 2
-\& perltidy \-l=80 \-iscl
-\& $vmsfile =~ s/;[\ed\e\-]*$//; # Clip off version number; we can use a newer version as well
-.Ve
-.Sp
-whereas without the \-iscl flag the line will be broken:
-.Sp
-.Vb 3
-\& perltidy \-l=80
-\& $vmsfile =~ s/;[\ed\e\-]*$//
-\& ; # Clip off version number; we can use a newer version as well
-.Ve
-.IP "\fB\-hsc\fR, \fB\-\-hanging\-side\-comments\fR" 4
-.IX Item "-hsc, --hanging-side-comments"
-By default, perltidy tries to identify and align \*(L"hanging side
-comments\*(R", which are something like this:
-.Sp
-.Vb 3
-\& my $IGNORE = 0; # This is a side comment
-\& # This is a hanging side comment
-\& # And so is this
-.Ve
-.Sp
-A comment is considered to be a hanging side comment if (1) it immediately
-follows a line with a side comment, or another hanging side comment, and
-(2) there is some leading whitespace on the line.
-To deactivate this feature, use \fB\-nhsc\fR or \fB\-\-nohanging\-side\-comments\fR.
-If block comments are preceded by a blank line, or have no leading
-whitespace, they will not be mistaken as hanging side comments.
-.IP "Closing Side Comments" 4
-.IX Item "Closing Side Comments"
-A closing side comment is a special comment which perltidy can
-automatically create and place after the closing brace of a code block.
-They can be useful for code maintenance and debugging. The command
-\&\fB\-csc\fR (or \fB\-\-closing\-side\-comments\fR) adds or updates closing side
-comments. For example, here is a small code snippet
-.Sp
-.Vb 8
-\& sub message {
-\& if ( !defined( $_[0] ) ) {
-\& print("Hello, World\en");
-\& }
-\& else {
-\& print( $_[0], "\en" );
-\& }
-\& }
-.Ve
-.Sp
-And here is the result of processing with \f(CW\*(C`perltidy \-csc\*(C'\fR:
-.Sp
-.Vb 8
-\& sub message {
-\& if ( !defined( $_[0] ) ) {
-\& print("Hello, World\en");
-\& }
-\& else {
-\& print( $_[0], "\en" );
-\& }
-\& } ## end sub message
-.Ve
-.Sp
-A closing side comment was added for \f(CW\*(C`sub message\*(C'\fR in this case, but not
-for the \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`else\*(C'\fR blocks, because they were below the 6 line
-cutoff limit for adding closing side comments. This limit may be
-changed with the \fB\-csci\fR command, described below.
-.Sp
-The command \fB\-dcsc\fR (or \fB\-\-delete\-closing\-side\-comments\fR) reverses this
-process and removes these comments.
-.Sp
-Several commands are available to modify the behavior of these two basic
-commands, \fB\-csc\fR and \fB\-dcsc\fR:
-.RS 4
-.IP "\fB\-csci=n\fR, or \fB\-\-closing\-side\-comment\-interval=n\fR" 4
-.IX Item "-csci=n, or --closing-side-comment-interval=n"
-where \f(CW\*(C`n\*(C'\fR is the minimum number of lines that a block must have in
-order for a closing side comment to be added. The default value is
-\&\f(CW\*(C`n=6\*(C'\fR. To illustrate:
-.Sp
-.Vb 9
-\& # perltidy \-csci=2 \-csc
-\& sub message {
-\& if ( !defined( $_[0] ) ) {
-\& print("Hello, World\en");
-\& } ## end if ( !defined( $_[0] ))
-\& else {
-\& print( $_[0], "\en" );
-\& } ## end else [ if ( !defined( $_[0] ))
-\& } ## end sub message
-.Ve
-.Sp
-Now the \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`else\*(C'\fR blocks are commented. However, now this has
-become very cluttered.
-.IP "\fB\-cscp=string\fR, or \fB\-\-closing\-side\-comment\-prefix=string\fR" 4
-.IX Item "-cscp=string, or --closing-side-comment-prefix=string"
-where string is the prefix used before the name of the block type. The
-default prefix, shown above, is \f(CW\*(C`## end\*(C'\fR. This string will be added to
-closing side comments, and it will also be used to recognize them in
-order to update, delete, and format them. Any comment identified as a
-closing side comment will be placed just a single space to the right of
-its closing brace.
-.IP "\fB\-cscl=string\fR, or \fB\-\-closing\-side\-comment\-list\fR" 4
-.IX Item "-cscl=string, or --closing-side-comment-list"
-where \f(CW\*(C`string\*(C'\fR is a list of block types to be tagged with closing side
-comments. By default, all code block types preceded by a keyword or
-label (such as \f(CW\*(C`if\*(C'\fR, \f(CW\*(C`sub\*(C'\fR, and so on) will be tagged. The \fB\-cscl\fR
-command changes the default list to be any selected block types; see
-\&\*(L"Specifying Block Types\*(R".
-For example, the following command
-requests that only \f(CW\*(C`sub\*(C'\fR's, labels, \f(CW\*(C`BEGIN\*(C'\fR, and \f(CW\*(C`END\*(C'\fR blocks be
-affected by any \fB\-csc\fR or \fB\-dcsc\fR operation:
-.Sp
-.Vb 1
-\& \-cscl="sub : BEGIN END"
-.Ve
-.IP "\fB\-csct=n\fR, or \fB\-\-closing\-side\-comment\-maximum\-text=n\fR" 4
-.IX Item "-csct=n, or --closing-side-comment-maximum-text=n"
-The text appended to certain block types, such as an \f(CW\*(C`if\*(C'\fR block, is
-whatever lies between the keyword introducing the block, such as \f(CW\*(C`if\*(C'\fR,
-and the opening brace. Since this might be too much text for a side
-comment, there needs to be a limit, and that is the purpose of this
-parameter. The default value is \f(CW\*(C`n=20\*(C'\fR, meaning that no additional
-tokens will be appended to this text after its length reaches 20
-characters. Omitted text is indicated with \f(CW\*(C`...\*(C'\fR. (Tokens, including
-sub names, are never truncated, however, so actual lengths may exceed
-this). To illustrate, in the above example, the appended text of the
-first block is \f(CW\*(C` ( !defined( $_[0] )...\*(C'\fR. The existing limit of
-\&\f(CW\*(C`n=20\*(C'\fR caused this text to be truncated, as indicated by the \f(CW\*(C`...\*(C'\fR. See
-the next flag for additional control of the abbreviated text.
-.IP "\fB\-cscb\fR, or \fB\-\-closing\-side\-comments\-balanced\fR" 4
-.IX Item "-cscb, or --closing-side-comments-balanced"
-As discussed in the previous item, when the
-closing-side-comment-maximum-text limit is exceeded the comment text must
-be truncated. Older versions of perltidy terminated with three dots, and this
-can still be achieved with \-ncscb:
-.Sp
-.Vb 2
-\& perltidy \-csc \-ncscb
-\& } ## end foreach my $foo (sort { $b cmp $a ...
-.Ve
-.Sp
-However this causes a problem with editors which cannot recognize
-comments or are not configured to do so because they cannot \*(L"bounce\*(R" around in
-the text correctly. The \fB\-cscb\fR flag has been added to
-help them by appending appropriate balancing structure:
-.Sp
-.Vb 2
-\& perltidy \-csc \-cscb
-\& } ## end foreach my $foo (sort { $b cmp $a ... })
-.Ve
-.Sp
-The default is \fB\-cscb\fR.
-.IP "\fB\-csce=n\fR, or \fB\-\-closing\-side\-comment\-else\-flag=n\fR" 4
-.IX Item "-csce=n, or --closing-side-comment-else-flag=n"
-The default, \fBn=0\fR, places the text of the opening \f(CW\*(C`if\*(C'\fR statement after any
-terminal \f(CW\*(C`else\*(C'\fR.
-.Sp
-If \fBn=2\fR is used, then each \f(CW\*(C`elsif\*(C'\fR is also given the text of the opening
-\&\f(CW\*(C`if\*(C'\fR statement. Also, an \f(CW\*(C`else\*(C'\fR will include the text of a preceding
-\&\f(CW\*(C`elsif\*(C'\fR statement. Note that this may result some long closing
-side comments.
-.Sp
-If \fBn=1\fR is used, the results will be the same as \fBn=2\fR whenever the
-resulting line length is less than the maximum allowed.
-.IP "\fB\-cscb\fR, or \fB\-\-closing\-side\-comments\-balanced\fR" 4
-.IX Item "-cscb, or --closing-side-comments-balanced"
-When using closing-side-comments, and the closing-side-comment-maximum-text
-limit is exceeded, then the comment text must be abbreviated.
-It is terminated with three dots if the \fB\-cscb\fR flag is negated:
-.Sp
-.Vb 2
-\& perltidy \-csc \-ncscb
-\& } ## end foreach my $foo (sort { $b cmp $a ...
-.Ve
-.Sp
-This causes a problem with older editors which do not recognize comments
-because they cannot \*(L"bounce\*(R" around in the text correctly. The \fB\-cscb\fR
-flag tries to help them by appending appropriate terminal balancing structures:
-.Sp
-.Vb 2
-\& perltidy \-csc \-cscb
-\& } ## end foreach my $foo (sort { $b cmp $a ... })
-.Ve
-.Sp
-The default is \fB\-cscb\fR.
-.IP "\fB\-cscw\fR, or \fB\-\-closing\-side\-comment\-warnings\fR" 4
-.IX Item "-cscw, or --closing-side-comment-warnings"
-This parameter is intended to help make the initial transition to the use of
-closing side comments.
-It causes two
-things to happen if a closing side comment replaces an existing, different
-closing side comment: first, an error message will be issued, and second, the
-original side comment will be placed alone on a new specially marked comment
-line for later attention.
-.Sp
-The intent is to avoid clobbering existing hand-written side comments
-which happen to match the pattern of closing side comments. This flag
-should only be needed on the first run with \fB\-csc\fR.
-.RE
-.RS 4
-.Sp
-\&\fBImportant Notes on Closing Side Comments:\fR
-.IP "\(bu" 4
-Closing side comments are only placed on lines terminated with a closing
-brace. Certain closing styles, such as the use of cuddled elses
-(\fB\-ce\fR), preclude the generation of some closing side comments.
-.IP "\(bu" 4
-Please note that adding or deleting of closing side comments takes
-place only through the commands \fB\-csc\fR or \fB\-dcsc\fR. The other commands,
-if used, merely modify the behavior of these two commands.
-.IP "\(bu" 4
-It is recommended that the \fB\-cscw\fR flag be used along with \fB\-csc\fR on
-the first use of perltidy on a given file. This will prevent loss of
-any existing side comment data which happens to have the csc prefix.
-.IP "\(bu" 4
-Once you use \fB\-csc\fR, you should continue to use it so that any
-closing side comments remain correct as code changes. Otherwise, these
-comments will become incorrect as the code is updated.
-.IP "\(bu" 4
-If you edit the closing side comments generated by perltidy, you must also
-change the prefix to be different from the closing side comment prefix.
-Otherwise, your edits will be lost when you rerun perltidy with \fB\-csc\fR. For
-example, you could simply change \f(CW\*(C`## end\*(C'\fR to be \f(CW\*(C`## End\*(C'\fR, since the test is
-case sensitive. You may also want to use the \fB\-ssc\fR flag to keep these
-modified closing side comments spaced the same as actual closing side comments.
-.IP "\(bu" 4
-Temporarily generating closing side comments is a useful technique for
-exploring and/or debugging a perl script, especially one written by someone
-else. You can always remove them with \fB\-dcsc\fR.
-.RE
-.RS 4
-.RE
-.IP "Static Block Comments" 4
-.IX Item "Static Block Comments"
-Static block comments are block comments with a special leading pattern,
-\&\f(CW\*(C`##\*(C'\fR by default, which will be treated slightly differently from other
-block comments. They effectively behave as if they had glue along their
-left and top edges, because they stick to the left edge and previous line
-when there is no blank spaces in those places. This option is
-particularly useful for controlling how commented code is displayed.
-.RS 4
-.IP "\fB\-sbc\fR, \fB\-\-static\-block\-comments\fR" 4
-.IX Item "-sbc, --static-block-comments"
-When \fB\-sbc\fR is used, a block comment with a special leading pattern, \f(CW\*(C`##\*(C'\fR by
-default, will be treated specially.
-.Sp
-Comments so identified are treated as follows:
-.RS 4
-.IP "\(bu" 4
-If there is no leading space on the line, then the comment will not
-be indented, and otherwise it may be,
-.IP "\(bu" 4
-no new blank line will be
-inserted before such a comment, and
-.IP "\(bu" 4
-such a comment will never become
-a hanging side comment.
-.RE
-.RS 4
-.Sp
-For example, assuming \f(CW@month_of_year\fR is
-left-adjusted:
-.Sp
-.Vb 4
-\& @month_of_year = ( # \-sbc (default)
-\& \*(AqJan\*(Aq, \*(AqFeb\*(Aq, \*(AqMar\*(Aq, \*(AqApr\*(Aq, \*(AqMay\*(Aq, \*(AqJun\*(Aq, \*(AqJul\*(Aq, \*(AqAug\*(Aq, \*(AqSep\*(Aq, \*(AqOct\*(Aq,
-\& ## \*(AqDec\*(Aq, \*(AqNov\*(Aq
-\& \*(AqNov\*(Aq, \*(AqDec\*(Aq);
-.Ve
-.Sp
-Without this convention, the above code would become
-.Sp
-.Vb 2
-\& @month_of_year = ( # \-nsbc
-\& \*(AqJan\*(Aq, \*(AqFeb\*(Aq, \*(AqMar\*(Aq, \*(AqApr\*(Aq, \*(AqMay\*(Aq, \*(AqJun\*(Aq, \*(AqJul\*(Aq, \*(AqAug\*(Aq, \*(AqSep\*(Aq, \*(AqOct\*(Aq,
-\&
-\& ## \*(AqDec\*(Aq, \*(AqNov\*(Aq
-\& \*(AqNov\*(Aq, \*(AqDec\*(Aq
-\& );
-.Ve
-.Sp
-which is not as clear.
-The default is to use \fB\-sbc\fR. This may be deactivated with \fB\-nsbc\fR.
-.RE
-.IP "\fB\-sbcp=string\fR, \fB\-\-static\-block\-comment\-prefix=string\fR" 4
-.IX Item "-sbcp=string, --static-block-comment-prefix=string"
-This parameter defines the prefix used to identify static block comments
-when the \fB\-sbc\fR parameter is set. The default prefix is \f(CW\*(C`##\*(C'\fR,
-corresponding to \f(CW\*(C`\-sbcp=##\*(C'\fR. The prefix is actually part of a perl
-pattern used to match lines and it must either begin with \f(CW\*(C`#\*(C'\fR or \f(CW\*(C`^#\*(C'\fR.
-In the first case a prefix ^\es* will be added to match any leading
-whitespace, while in the second case the pattern will match only
-comments with no leading whitespace. For example, to
-identify all comments as static block comments, one would use \f(CW\*(C`\-sbcp=#\*(C'\fR.
-To identify all left-adjusted comments as static block comments, use \f(CW\*(C`\-sbcp=\*(Aq^#\*(Aq\*(C'\fR.
-.Sp
-Please note that \fB\-sbcp\fR merely defines the pattern used to identify static
-block comments; it will not be used unless the switch \fB\-sbc\fR is set. Also,
-please be aware that since this string is used in a perl regular expression
-which identifies these comments, it must enable a valid regular expression to
-be formed.
-.Sp
-A pattern which can be useful is:
-.Sp
-.Vb 1
-\& \-sbcp=^#{2,}[^\es#]
-.Ve
-.Sp
-This pattern requires a static block comment to have at least one character
-which is neither a # nor a space. It allows a line containing only '#'
-characters to be rejected as a static block comment. Such lines are often used
-at the start and end of header information in subroutines and should not be
-separated from the intervening comments, which typically begin with just a
-single '#'.
-.IP "\fB\-osbc\fR, \fB\-\-outdent\-static\-block\-comments\fR" 4
-.IX Item "-osbc, --outdent-static-block-comments"
-The command \fB\-osbc\fR will cause static block comments to be outdented by 2
-spaces (or whatever \fB\-ci=n\fR has been set to), if possible.
-.RE
-.RS 4
-.RE
-.IP "Static Side Comments" 4
-.IX Item "Static Side Comments"
-Static side comments are side comments with a special leading pattern.
-This option can be useful for controlling how commented code is displayed
-when it is a side comment.
-.RS 4
-.IP "\fB\-ssc\fR, \fB\-\-static\-side\-comments\fR" 4
-.IX Item "-ssc, --static-side-comments"
-When \fB\-ssc\fR is used, a side comment with a static leading pattern, which is
-\&\f(CW\*(C`##\*(C'\fR by default, will be spaced only a single space from previous
-character, and it will not be vertically aligned with other side comments.
-.Sp
-The default is \fB\-nssc\fR.
-.IP "\fB\-sscp=string\fR, \fB\-\-static\-side\-comment\-prefix=string\fR" 4
-.IX Item "-sscp=string, --static-side-comment-prefix=string"
-This parameter defines the prefix used to identify static side comments
-when the \fB\-ssc\fR parameter is set. The default prefix is \f(CW\*(C`##\*(C'\fR,
-corresponding to \f(CW\*(C`\-sscp=##\*(C'\fR.
-.Sp
-Please note that \fB\-sscp\fR merely defines the pattern used to identify
-static side comments; it will not be used unless the switch \fB\-ssc\fR is
-set. Also, note that this string is used in a perl regular expression
-which identifies these comments, so it must enable a valid regular
-expression to be formed.
-.RE
-.RS 4
-.RE
-.SS "Skipping Selected Sections of Code"
-.IX Subsection "Skipping Selected Sections of Code"
-Selected lines of code may be passed verbatim to the output without any
-formatting. This feature is enabled by default but can be disabled with
-the \fB\-\-noformat\-skipping\fR or \fB\-nfs\fR flag. It should be used sparingly to
-avoid littering code with markers, but it might be helpful for working
-around occasional problems. For example it might be useful for keeping
-the indentation of old commented code unchanged, keeping indentation of
-long blocks of aligned comments unchanged, keeping certain list
-formatting unchanged, or working around a glitch in perltidy.
-.IP "\fB\-fs\fR, \fB\-\-format\-skipping\fR" 4
-.IX Item "-fs, --format-skipping"
-This flag, which is enabled by default, causes any code between
-special beginning and ending comment markers to be passed to the
-output without formatting. The default beginning marker is #<<<
-and the default ending marker is #>>> but they
-may be changed (see next items below). Additional text may appear on
-these special comment lines provided that it is separated from the
-marker by at least one space. For example
-.Sp
-.Vb 7
-\& #<<< do not let perltidy touch this
-\& my @list = (1,
-\& 1, 1,
-\& 1, 2, 1,
-\& 1, 3, 3, 1,
-\& 1, 4, 6, 4, 1,);
-\& #>>>
-.Ve
-.Sp
-The comment markers may be placed at any location that a block comment may
-appear. If they do not appear to be working, use the \-log flag and examine the
-\&\fI.LOG\fR file. Use \fB\-nfs\fR to disable this feature.
-.IP "\fB\-fsb=string\fR, \fB\-\-format\-skipping\-begin=string\fR" 4
-.IX Item "-fsb=string, --format-skipping-begin=string"
-The \fB\-fsb=string\fR parameter may be used to change the beginning marker for
-format skipping. The default is equivalent to \-fsb='#<<<'. The string that
-you enter must begin with a # and should be in quotes as necessary to get past
-the command shell of your system. It is actually the leading text of a pattern
-that is constructed by appending a '\es', so you must also include backslashes
-for characters to be taken literally rather than as patterns.
-.Sp
-Some examples show how example strings become patterns:
-.Sp
-.Vb 3
-\& \-fsb=\*(Aq#\e{\e{\e{\*(Aq becomes /^#\e{\e{\e{\es/ which matches #{{{ but not #{{{{
-\& \-fsb=\*(Aq#\e*\e*\*(Aq becomes /^#\e*\e*\es/ which matches #** but not #***
-\& \-fsb=\*(Aq#\e*{2,}\*(Aq becomes /^#\e*{2,}\es/ which matches #** and #*****
-.Ve
-.IP "\fB\-fse=string\fR, \fB\-\-format\-skipping\-end=string\fR" 4
-.IX Item "-fse=string, --format-skipping-end=string"
-The \fB\-fsb=string\fR is the corresponding parameter used to change the
-ending marker for format skipping. The default is equivalent to
-\&\-fse='#<<<'.
-.SS "Line Break Control"
-.IX Subsection "Line Break Control"
-The parameters in this section control breaks after
-non-blank lines of code. Blank lines are controlled
-separately by parameters in the section \*(L"Blank Line
-Control\*(R".
-.IP "\fB\-fnl\fR, \fB\-\-freeze\-newlines\fR" 4
-.IX Item "-fnl, --freeze-newlines"
-If you do not want any changes to the line breaks within
-lines of code in your script, set
-\&\fB\-fnl\fR, and they will remain fixed, and the rest of the commands in
-this section and sections
-\&\*(L"Controlling List Formatting\*(R",
-\&\*(L"Retaining or Ignoring Existing Line Breaks\*(R".
-You may want to use \fB\-noll\fR with this.
-.Sp
-Note: If you also want to keep your blank lines exactly
-as they are, you can use the \fB\-fbl\fR flag which is described
-in the section \*(L"Blank Line Control\*(R".
-.IP "\fB\-ce\fR, \fB\-\-cuddled\-else\fR" 4
-.IX Item "-ce, --cuddled-else"
-Enable the \*(L"cuddled else\*(R" style, in which \f(CW\*(C`else\*(C'\fR and \f(CW\*(C`elsif\*(C'\fR are
-follow immediately after the curly brace closing the previous block.
-The default is not to use cuddled elses, and is indicated with the flag
-\&\fB\-nce\fR or \fB\-\-nocuddled\-else\fR. Here is a comparison of the
-alternatives:
-.Sp
-.Vb 5
-\& if ($task) {
-\& yyy();
-\& } else { # \-ce
-\& zzz();
-\& }
-\&
-\& if ($task) {
-\& yyy();
-\& }
-\& else { # \-nce (default)
-\& zzz();
-\& }
-.Ve
-.IP "\fB\-cb\fR, \fB\-\-cuddled\-blocks\fR" 4
-.IX Item "-cb, --cuddled-blocks"
-This flag enables the \*(L"cuddled else\*(R" format style on a chain of specified block
-types. The default is to apply it to a chain consisting of try-catch-finally
-blocks, but it can apply to any desired chain of blocks by specifying their
-names on a separate parameter \fB\-cbl\fR, described in the next section.
-.Sp
-.Vb 9
-\& # perltidy \-cb:
-\& try {
-\& throw Error::Simple( "ok 2\en", 2 );
-\& } catch Error::Simple with {
-\& my $err = shift;
-\& print "$err";
-\& } finally {
-\& print "ok 3\en";
-\& };
-.Ve
-.Sp
-Cuddling between a pair of code blocks requires that the closing brace of the
-first block start a new line. If this block is entirely on one line in the
-input file, it is necessary to decide if it should be broken to allow cuddling.
-This decision is controlled by the flag \fB\-cbo=n\fR discussed below. The default
-and recommended value of \fB\-cbo=1\fR bases this decision on the first block in
-the chain. If it spans multiple lines then cuddling is made and continues
-along the chain, regardless of the sizes of subsequent blocks. Otherwise, short
-lines remain intact.
-.Sp
-So for example, the \fB\-cb\fR flag would not have any effect if the above snippet
-is rewritten as
-.Sp
-.Vb 3
-\& try { throw Error::Simple( "ok 2\en", 2 ); }
-\& catch Error::Simple with { my $err = shift; print "$err"; }
-\& finally { print "ok 3\en"; };
-.Ve
-.Sp
-If the first block spans multiple lines, then cuddling can be done and will
-continue for the subsequent blocks in the chain, as illustrated in the previous
-snippet.
-.Sp
-If there are blank lines between cuddled blocks they will be eliminated. If
-there are comments after the closing brace where cuddling would occur then
-cuddling will be prevented. If this occurs, cuddling will restart later in the
-chain if possible.
-.Sp
-The default for this parameter is \fB\-\-nocuddled\-blocks\fR
-.IP "\fB\-cbl\fR, \fB\-\-cuddled\-block\-list\fR" 4
-.IX Item "-cbl, --cuddled-block-list"
-The block types to which the \fB\-cuddled\-blocks\fR style applies is defined by
-this parameter. This parameter is a character string, giving a list of
-block types separated by dashes.
-.Sp
-The default value for this string is
-.Sp
-.Vb 1
-\& \-cbl="try\-catch\-finally"
-.Ve
-.Sp
-This string will cause cuddled formatting to be applied to every block in a chain
-starting with a \*(L"try\*(R" and followed by any number of \*(L"catch\*(R" and \*(L"finally\*(R"
-blocks.
-.Sp
-In general, a string describing a chain of blocks has the form
-.Sp
-.Vb 1
-\& \-cbl="word1\-word2\-word3\-...\-wordn"
-.Ve
-.Sp
-In this case, a chain begins when an opening block brace preceded by word1 in
-the list is encountered. The chain continues if the closing block brace is
-followed immediately by any of word2, word3, etc.
-.Sp
-If the leading word, word1, might be repeated later in a chain then it should
-also be included amoung the secondary words.
-.Sp
-Multiple chain types may be specified by separating the strings with commas or
-spaces. So for example if we have two chains of code blocks, f1\-f2\-f3 and g1\-g2\-g3\-g4,
-they could be specified as
-.Sp
-.Vb 3
-\& \-cbl="f1\-f2\-f3 g1\-g2\-g3\-g4"
-\&or
-\& \-cbl=f1\-f2\-f3,g1\-g2\-g3\-g4
-.Ve
-.Sp
-Spaces are easier to read but commas may avoid quotation difficulties when
-entering data in a command shell.
-.Sp
-To define secondary words that apply to all block types, other than those explicitly specified,
-the leading word can be omitted. For example, the built-in cuddled-else format specified by
-the \fB\-ce\fR flag can be approximately specified by
-.Sp
-.Vb 3
-\& \-cbl="if\-else\-elsif unless\-else\-elsif \-continue"
-\&or
-\& \-cbl=if\-else\-elsif,unless\-else\-elsif,\-continue
-.Ve
-.Sp
-The final string \-continue allows cuddling the optional continue block
-which may follow may other block types.
-.Sp
-As a diagnostic check, the flag \fB\-\-dump\-cuddled\-block\-list\fR or \fB\-dcbl\fR can be
-used to view the hash of values this flag creates.
-.Sp
-Finally, note that the \fB\-cbl\fR flag by itself merely specifies which blocks are formatted
-with the cuddled format. It has no effect unless this formatting style is activated with
-\&\fB\-cb\fR.
-.IP "\fB\-cbo=n\fR, \fB\-\-cuddled\-break\-option=n\fR" 4
-.IX Item "-cbo=n, --cuddled-break-option=n"
-Cuddled formatting is only possible between a pair of code blocks if the
-closing brace of the first block starts a new line. If a block is encountered
-which is entirely on a single line, and cuddled formatting is selected, it is
-necessary to make a decision as to whether or not to \*(L"break\*(R" the block, meaning
-to cause it to span multiple lines. This parameter controls that decision. The
-options are:
-.Sp
-.Vb 4
-\& cbo=0 Never force a short block to break.
-\& cbo=1 If the first of a pair of blocks is broken in the input file,
-\& then break the second.
-\& cbo=2 Break open all blocks for maximal cuddled formatting.
-.Ve
-.Sp
-The default and recommended value is \fBcbo=1\fR. With this value, if the starting
-block of a chain spans multiple lines, then a cascade of breaks will occur for
-remaining blocks causing the entire chain to be cuddled.
-.Sp
-The option \fBcbo=0\fR can produce erratic cuddling if there are numerous one-line
-blocks.
-.Sp
-The option \fBcbo=2\fR produces maximal cuddling but will not allow any short blocks.
-.Sp
-Note: at present, this option currently only applies to blocks controlled by
-the \fB\-cb\fR flag. Cuddling under the \fB\-ce\fR flag corresponds approximately to
-\&\fB\-cbo=1\fR but cannot currently be changed.
-.IP "\fB\-bl\fR, \fB\-\-opening\-brace\-on\-new\-line\fR" 4
-.IX Item "-bl, --opening-brace-on-new-line"
-Use the flag \fB\-bl\fR to place the opening brace on a new line:
-.Sp
-.Vb 4
-\& if ( $input_file eq \*(Aq\-\*(Aq ) # \-bl
-\& {
-\& important_function();
-\& }
-.Ve
-.Sp
-This flag applies to all structural blocks, including named sub's (unless
-the \fB\-sbl\fR flag is set \*(-- see next item).
-.Sp
-The default style, \fB\-nbl\fR, places an opening brace on the same line as
-the keyword introducing it. For example,
-.Sp
-.Vb 1
-\& if ( $input_file eq \*(Aq\-\*(Aq ) { # \-nbl (default)
-.Ve
-.IP "\fB\-sbl\fR, \fB\-\-opening\-sub\-brace\-on\-new\-line\fR" 4
-.IX Item "-sbl, --opening-sub-brace-on-new-line"
-The flag \fB\-sbl\fR can be used to override the value of \fB\-bl\fR for
-the opening braces of named sub's. For example,
-.Sp
-.Vb 1
-\& perltidy \-sbl
-.Ve
-.Sp
-produces this result:
-.Sp
-.Vb 9
-\& sub message
-\& {
-\& if (!defined($_[0])) {
-\& print("Hello, World\en");
-\& }
-\& else {
-\& print($_[0], "\en");
-\& }
-\& }
-.Ve
-.Sp
-This flag is negated with \fB\-nsbl\fR. If \fB\-sbl\fR is not specified,
-the value of \fB\-bl\fR is used.
-.IP "\fB\-asbl\fR, \fB\-\-opening\-anonymous\-sub\-brace\-on\-new\-line\fR" 4
-.IX Item "-asbl, --opening-anonymous-sub-brace-on-new-line"
-The flag \fB\-asbl\fR is like the \fB\-sbl\fR flag except that it applies
-to anonymous sub's instead of named subs. For example
-.Sp
-.Vb 1
-\& perltidy \-asbl
-.Ve
-.Sp
-produces this result:
-.Sp
-.Vb 9
-\& $a = sub
-\& {
-\& if ( !defined( $_[0] ) ) {
-\& print("Hello, World\en");
-\& }
-\& else {
-\& print( $_[0], "\en" );
-\& }
-\& };
-.Ve
-.Sp
-This flag is negated with \fB\-nasbl\fR, and the default is \fB\-nasbl\fR.
-.IP "\fB\-bli\fR, \fB\-\-brace\-left\-and\-indent\fR" 4
-.IX Item "-bli, --brace-left-and-indent"
-The flag \fB\-bli\fR is the same as \fB\-bl\fR but in addition it causes one
-unit of continuation indentation ( see \fB\-ci\fR ) to be placed before
-an opening and closing block braces.
-.Sp
-For example,
-.Sp
-.Vb 4
-\& if ( $input_file eq \*(Aq\-\*(Aq ) # \-bli
-\& {
-\& important_function();
-\& }
-.Ve
-.Sp
-By default, this extra indentation occurs for blocks of type:
-\&\fBif\fR, \fBelsif\fR, \fBelse\fR, \fBunless\fR, \fBfor\fR, \fBforeach\fR, \fBsub\fR,
-\&\fBwhile\fR, \fBuntil\fR, and also with a preceding label. The next item
-shows how to change this.
-.IP "\fB\-blil=s\fR, \fB\-\-brace\-left\-and\-indent\-list=s\fR" 4
-.IX Item "-blil=s, --brace-left-and-indent-list=s"
-Use this parameter to change the types of block braces for which the
-\&\fB\-bli\fR flag applies; see \*(L"Specifying Block Types\*(R". For example,
-\&\fB\-blil='if elsif else'\fR would apply it to only \f(CW\*(C`if/elsif/else\*(C'\fR blocks.
-.IP "\fB\-bar\fR, \fB\-\-opening\-brace\-always\-on\-right\fR" 4
-.IX Item "-bar, --opening-brace-always-on-right"
-The default style, \fB\-nbl\fR places the opening code block brace on a new
-line if it does not fit on the same line as the opening keyword, like
-this:
-.Sp
-.Vb 5
-\& if ( $bigwasteofspace1 && $bigwasteofspace2
-\& || $bigwasteofspace3 && $bigwasteofspace4 )
-\& {
-\& big_waste_of_time();
-\& }
-.Ve
-.Sp
-To force the opening brace to always be on the right, use the \fB\-bar\fR
-flag. In this case, the above example becomes
-.Sp
-.Vb 4
-\& if ( $bigwasteofspace1 && $bigwasteofspace2
-\& || $bigwasteofspace3 && $bigwasteofspace4 ) {
-\& big_waste_of_time();
-\& }
-.Ve
-.Sp
-A conflict occurs if both \fB\-bl\fR and \fB\-bar\fR are specified.
-.IP "\fB\-otr\fR, \fB\-\-opening\-token\-right\fR and related flags" 4
-.IX Item "-otr, --opening-token-right and related flags"
-The \fB\-otr\fR flag is a hint that perltidy should not place a break between a
-comma and an opening token. For example:
-.Sp
-.Vb 6
-\& # default formatting
-\& push @{ $self\->{$module}{$key} },
-\& {
-\& accno => $ref\->{accno},
-\& description => $ref\->{description}
-\& };
-\&
-\& # perltidy \-otr
-\& push @{ $self\->{$module}{$key} }, {
-\& accno => $ref\->{accno},
-\& description => $ref\->{description}
-\& };
-.Ve
-.Sp
-The flag \fB\-otr\fR is actually an abbreviation for three other flags
-which can be used to control parens, hash braces, and square brackets
-separately if desired:
-.Sp
-.Vb 3
-\& \-opr or \-\-opening\-paren\-right
-\& \-ohbr or \-\-opening\-hash\-brace\-right
-\& \-osbr or \-\-opening\-square\-bracket\-right
-.Ve
-.IP "\fB\-wn\fR, \fB\-\-weld\-nested\-containers\fR" 4
-.IX Item "-wn, --weld-nested-containers"
-The \fB\-wn\fR flag causes closely nested pairs of opening and closing container
-symbols (curly braces, brackets, or parens) to be \*(L"welded\*(R" together, meaning
-that they are treated as if combined into a single unit, with the indentation
-of the innermost code reduced to be as if there were just a single container
-symbol.
-.Sp
-For example:
-.Sp
-.Vb 6
-\& # default formatting
-\& do {
-\& {
-\& next if $x == $y;
-\& }
-\& } until $x++ > $z;
-\&
-\& # perltidy \-wn
-\& do { {
-\& next if $x == $y;
-\& } } until $x++ > $z;
-.Ve
-.Sp
-When this flag is set perltidy makes a preliminary pass through the file and
-identifies all nested pairs of containers. To qualify as a nested pair, the
-closing container symbols must be immediately adjacent. The opening symbols
-must either be adjacent, or, if the outer opening symbol is an opening
-paren, they may be separated by any single non-container symbol or something
-that looks like a function evaluation.
-.Sp
-Any container symbol may serve as both the inner container of one pair and as
-the outer container of an adjacent pair. Consequently, any number of adjacent
-opening or closing symbols may join together in weld. For example, here are
-three levels of wrapped function calls:
-.Sp
-.Vb 9
-\& # default formatting
-\& my (@date_time) = Localtime(
-\& Date_to_Time(
-\& Add_Delta_DHMS(
-\& $year, $month, $day, $hour, $minute, $second,
-\& \*(Aq0\*(Aq, $offset, \*(Aq0\*(Aq, \*(Aq0\*(Aq
-\& )
-\& )
-\& );
-\&
-\& # perltidy \-wn
-\& my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
-\& $year, $month, $day, $hour, $minute, $second,
-\& \*(Aq0\*(Aq, $offset, \*(Aq0\*(Aq, \*(Aq0\*(Aq
-\& ) ) );
-.Ve
-.Sp
-Notice how the indentation of the inner lines are reduced by two levels in this
-case. This example also shows the typical result of this formatting, namely it
-is a sandwich consisting of an initial opening layer, a central section of any
-complexity forming the \*(L"meat\*(R" of the sandwich, and a final closing layer. This
-predictable structure helps keep the compacted structure readable.
-.Sp
-The inner sandwich layer is required to be at least one line thick. If this
-cannot be achieved, welding does not occur. This constraint can cause
-formatting to take a couple of iterations to stabilize when it is first applied
-to a script. The \fB\-conv\fR flag can be used to insure that the final format is
-achieved in a single run.
-.Sp
-Here is an example illustrating a welded container within a welded containers:
-.Sp
-.Vb 11
-\& # default formatting
-\& $x\->badd(
-\& bmul(
-\& $class\->new(
-\& abs(
-\& $sx * int( $xr\->numify() ) & $sy * int( $yr\->numify() )
-\& )
-\& ),
-\& $m
-\& )
-\& );
-\&
-\& # perltidy \-wn
-\& $x\->badd( bmul(
-\& $class\->new( abs(
-\& $sx * int( $xr\->numify() ) & $sy * int( $yr\->numify() )
-\& ) ),
-\& $m
-\& ) );
-.Ve
-.Sp
-This format option is quite general but there are some limitations.
-.Sp
-One limitiation is that any line length limit still applies and can cause long
-welded sections to be broken into multiple lines.
-.Sp
-Another limitation is that an opening symbol which delimits quoted text cannot
-be included in a welded pair. This is because quote delimiters are treated
-specially in perltidy.
-.Sp
-Finally, the stacking of containers defined by this flag have priority over
-any other container stacking flags. This is because any welding is done first.
-.IP "\fBVertical tightness\fR of non-block curly braces, parentheses, and square brackets." 4
-.IX Item "Vertical tightness of non-block curly braces, parentheses, and square brackets."
-These parameters control what shall be called vertical tightness. Here are the
-main points:
-.RS 4
-.IP "\(bu" 4
-Opening tokens (except for block braces) are controlled by \fB\-vt=n\fR, or
-\&\fB\-\-vertical\-tightness=n\fR, where
-.Sp
-.Vb 4
-\& \-vt=0 always break a line after opening token (default).
-\& \-vt=1 do not break unless this would produce more than one
-\& step in indentation in a line.
-\& \-vt=2 never break a line after opening token
-.Ve
-.IP "\(bu" 4
-You must also use the \fB\-lp\fR flag when you use the \fB\-vt\fR flag; the
-reason is explained below.
-.IP "\(bu" 4
-Closing tokens (except for block braces) are controlled by \fB\-vtc=n\fR, or
-\&\fB\-\-vertical\-tightness\-closing=n\fR, where
-.Sp
-.Vb 5
-\& \-vtc=0 always break a line before a closing token (default),
-\& \-vtc=1 do not break before a closing token which is followed
-\& by a semicolon or another closing token, and is not in
-\& a list environment.
-\& \-vtc=2 never break before a closing token.
-.Ve
-.Sp
-The rules for \fB\-vtc=1\fR are designed to maintain a reasonable balance
-between tightness and readability in complex lists.
-.IP "\(bu" 4
-Different controls may be applied to different token types,
-and it is also possible to control block braces; see below.
-.IP "\(bu" 4
-Finally, please note that these vertical tightness flags are merely
-hints to the formatter, and it cannot always follow them. Things which
-make it difficult or impossible include comments, blank lines, blocks of
-code within a list, and possibly the lack of the \fB\-lp\fR parameter.
-Also, these flags may be ignored for very small lists (2 or 3 lines in
-length).
-.RE
-.RS 4
-.Sp
-Here are some examples:
-.Sp
-.Vb 7
-\& # perltidy \-lp \-vt=0 \-vtc=0
-\& %romanNumerals = (
-\& one => \*(AqI\*(Aq,
-\& two => \*(AqII\*(Aq,
-\& three => \*(AqIII\*(Aq,
-\& four => \*(AqIV\*(Aq,
-\& );
-\&
-\& # perltidy \-lp \-vt=1 \-vtc=0
-\& %romanNumerals = ( one => \*(AqI\*(Aq,
-\& two => \*(AqII\*(Aq,
-\& three => \*(AqIII\*(Aq,
-\& four => \*(AqIV\*(Aq,
-\& );
-\&
-\& # perltidy \-lp \-vt=1 \-vtc=1
-\& %romanNumerals = ( one => \*(AqI\*(Aq,
-\& two => \*(AqII\*(Aq,
-\& three => \*(AqIII\*(Aq,
-\& four => \*(AqIV\*(Aq, );
-.Ve
-.Sp
-The difference between \fB\-vt=1\fR and \fB\-vt=2\fR is shown here:
-.Sp
-.Vb 6
-\& # perltidy \-lp \-vt=1
-\& $init\->add(
-\& mysprintf( "(void)find_threadsv(%s);",
-\& cstring( $threadsv_names[ $op\->targ ] )
-\& )
-\& );
-\&
-\& # perltidy \-lp \-vt=2
-\& $init\->add( mysprintf( "(void)find_threadsv(%s);",
-\& cstring( $threadsv_names[ $op\->targ ] )
-\& )
-\& );
-.Ve
-.Sp
-With \fB\-vt=1\fR, the line ending in \f(CW\*(C`add(\*(C'\fR does not combine with the next
-line because the next line is not balanced. This can help with
-readability, but \fB\-vt=2\fR can be used to ignore this rule.
-.Sp
-The tightest, and least readable, code is produced with both \f(CW\*(C`\-vt=2\*(C'\fR and
-\&\f(CW\*(C`\-vtc=2\*(C'\fR:
-.Sp
-.Vb 3
-\& # perltidy \-lp \-vt=2 \-vtc=2
-\& $init\->add( mysprintf( "(void)find_threadsv(%s);",
-\& cstring( $threadsv_names[ $op\->targ ] ) ) );
-.Ve
-.Sp
-Notice how the code in all of these examples collapses vertically as
-\&\fB\-vt\fR increases, but the indentation remains unchanged. This is
-because perltidy implements the \fB\-vt\fR parameter by first formatting as
-if \fB\-vt=0\fR, and then simply overwriting one output line on top of the
-next, if possible, to achieve the desired vertical tightness. The
-\&\fB\-lp\fR indentation style has been designed to allow this vertical
-collapse to occur, which is why it is required for the \fB\-vt\fR parameter.
-.Sp
-The \fB\-vt=n\fR and \fB\-vtc=n\fR parameters apply to each type of container
-token. If desired, vertical tightness controls can be applied
-independently to each of the closing container token types.
-.Sp
-The parameters for controlling parentheses are \fB\-pvt=n\fR or
-\&\fB\-\-paren\-vertical\-tightness=n\fR, and \fB\-pcvt=n\fR or
-\&\fB\-\-paren\-vertical\-tightness\-closing=n\fR.
-.Sp
-Likewise, the parameters for square brackets are \fB\-sbvt=n\fR or
-\&\fB\-\-square\-bracket\-vertical\-tightness=n\fR, and \fB\-sbcvt=n\fR or
-\&\fB\-\-square\-bracket\-vertical\-tightness\-closing=n\fR.
-.Sp
-Finally, the parameters for controlling non-code block braces are
-\&\fB\-bvt=n\fR or \fB\-\-brace\-vertical\-tightness=n\fR, and \fB\-bcvt=n\fR or
-\&\fB\-\-brace\-vertical\-tightness\-closing=n\fR.
-.Sp
-In fact, the parameter \fB\-vt=n\fR is actually just an abbreviation for
-\&\fB\-pvt=n \-bvt=n sbvt=n\fR, and likewise \fB\-vtc=n\fR is an abbreviation
-for \fB\-pvtc=n \-bvtc=n sbvtc=n\fR.
-.RE
-.IP "\fB\-bbvt=n\fR or \fB\-\-block\-brace\-vertical\-tightness=n\fR" 4
-.IX Item "-bbvt=n or --block-brace-vertical-tightness=n"
-The \fB\-bbvt=n\fR flag is just like the \fB\-vt=n\fR flag but applies
-to opening code block braces.
-.Sp
-.Vb 4
-\& \-bbvt=0 break after opening block brace (default).
-\& \-bbvt=1 do not break unless this would produce more than one
-\& step in indentation in a line.
-\& \-bbvt=2 do not break after opening block brace.
-.Ve
-.Sp
-It is necessary to also use either \fB\-bl\fR or \fB\-bli\fR for this to work,
-because, as with other vertical tightness controls, it is implemented by
-simply overwriting a line ending with an opening block brace with the
-subsequent line. For example:
-.Sp
-.Vb 10
-\& # perltidy \-bli \-bbvt=0
-\& if ( open( FILE, "< $File" ) )
-\& {
-\& while ( $File = <FILE> )
-\& {
-\& $In .= $File;
-\& $count++;
-\& }
-\& close(FILE);
-\& }
-\&
-\& # perltidy \-bli \-bbvt=1
-\& if ( open( FILE, "< $File" ) )
-\& { while ( $File = <FILE> )
-\& { $In .= $File;
-\& $count++;
-\& }
-\& close(FILE);
-\& }
-.Ve
-.Sp
-By default this applies to blocks associated with keywords \fBif\fR,
-\&\fBelsif\fR, \fBelse\fR, \fBunless\fR, \fBfor\fR, \fBforeach\fR, \fBsub\fR, \fBwhile\fR,
-\&\fBuntil\fR, and also with a preceding label. This can be changed with
-the parameter \fB\-bbvtl=string\fR, or
-\&\fB\-\-block\-brace\-vertical\-tightness\-list=string\fR, where \fBstring\fR is a
-space-separated list of block types. For more information on the
-possible values of this string, see \*(L"Specifying Block Types\*(R"
-.Sp
-For example, if we want to just apply this style to \f(CW\*(C`if\*(C'\fR,
-\&\f(CW\*(C`elsif\*(C'\fR, and \f(CW\*(C`else\*(C'\fR blocks, we could use
-\&\f(CW\*(C`perltidy \-bli \-bbvt=1 \-bbvtl=\*(Aqif elsif else\*(Aq\*(C'\fR.
-.Sp
-There is no vertical tightness control for closing block braces; with
-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 \fB\-scbb\fR.
-.IP "\fB\-sot\fR, \fB\-\-stack\-opening\-tokens\fR and related flags" 4
-.IX Item "-sot, --stack-opening-tokens and related flags"
-The \fB\-sot\fR flag tells perltidy to \*(L"stack\*(R" opening tokens
-when possible to avoid lines with isolated opening tokens.
-.Sp
-For example:
-.Sp
-.Vb 8
-\& # default
-\& $opt_c = Text::CSV_XS\->new(
-\& {
-\& binary => 1,
-\& sep_char => $opt_c,
-\& always_quote => 1,
-\& }
-\& );
-\&
-\& # \-sot
-\& $opt_c = Text::CSV_XS\->new( {
-\& binary => 1,
-\& sep_char => $opt_c,
-\& always_quote => 1,
-\& }
-\& );
-.Ve
-.Sp
-For detailed control of individual closing tokens the following
-controls can be used:
-.Sp
-.Vb 4
-\& \-sop or \-\-stack\-opening\-paren
-\& \-sohb or \-\-stack\-opening\-hash\-brace
-\& \-sosb or \-\-stack\-opening\-square\-bracket
-\& \-sobb or \-\-stack\-opening\-block\-brace
-.Ve
-.Sp
-The flag \fB\-sot\fR is an abbreviation for \fB\-sop \-sohb \-sosb\fR.
-.Sp
-The flag \fB\-sobb\fR is a abbreviation for \fB\-bbvt=2 \-bbvtl='*'\fR. This
-will case a cascade of opening block braces to appear on a single line,
-although this an uncommon occurrence except in test scripts.
-.IP "\fB\-sct\fR, \fB\-\-stack\-closing\-tokens\fR and related flags" 4
-.IX Item "-sct, --stack-closing-tokens and related flags"
-The \fB\-sct\fR flag tells perltidy to \*(L"stack\*(R" closing tokens
-when possible to avoid lines with isolated closing tokens.
-.Sp
-For example:
-.Sp
-.Vb 8
-\& # default
-\& $opt_c = Text::CSV_XS\->new(
-\& {
-\& binary => 1,
-\& sep_char => $opt_c,
-\& always_quote => 1,
-\& }
-\& );
-\&
-\& # \-sct
-\& $opt_c = Text::CSV_XS\->new(
-\& {
-\& binary => 1,
-\& sep_char => $opt_c,
-\& always_quote => 1,
-\& } );
-.Ve
-.Sp
-The \fB\-sct\fR flag is somewhat similar to the \fB\-vtc\fR flags, and in some
-cases it can give a similar result. The difference is that the \fB\-vtc\fR
-flags try to avoid lines with leading opening tokens by \*(L"hiding\*(R" them at
-the end of a previous line, whereas the \fB\-sct\fR flag merely tries to
-reduce the number of lines with isolated closing tokens by stacking them
-but does not try to hide them. For example:
-.Sp
-.Vb 6
-\& # \-vtc=2
-\& $opt_c = Text::CSV_XS\->new(
-\& {
-\& binary => 1,
-\& sep_char => $opt_c,
-\& always_quote => 1, } );
-.Ve
-.Sp
-For detailed control of the stacking of individual closing tokens the
-following controls can be used:
-.Sp
-.Vb 4
-\& \-scp or \-\-stack\-closing\-paren
-\& \-schb or \-\-stack\-closing\-hash\-brace
-\& \-scsb or \-\-stack\-closing\-square\-bracket
-\& \-scbb or \-\-stack\-closing\-block\-brace
-.Ve
-.Sp
-The flag \fB\-sct\fR is an abbreviation for stacking the non-block closing
-tokens, \fB\-scp \-schb \-scsb\fR.
-.Sp
-Stacking of closing block braces, \fB\-scbb\fR, causes a cascade of isolated
-closing block braces to be combined into a single line as in the following
-example:
-.Sp
-.Vb 7
-\& # \-scbb:
-\& for $w1 (@w1) {
-\& for $w2 (@w2) {
-\& for $w3 (@w3) {
-\& for $w4 (@w4) {
-\& push( @lines, "$w1 $w2 $w3 $w4\en" );
-\& } } } }
-.Ve
-.Sp
-To simplify input even further for the case in which both opening and closing
-non-block containers are stacked, the flag \fB\-sac\fR or \fB\-\-stack\-all\-containers\fR
-is an abbreviation for \fB\-sot \-sot\fR.
-.IP "\fB\-dnl\fR, \fB\-\-delete\-old\-newlines\fR" 4
-.IX Item "-dnl, --delete-old-newlines"
-By default, perltidy first deletes all old line break locations, and then it
-looks for good break points to match the desired line length. Use \fB\-ndnl\fR
-or \fB\-\-nodelete\-old\-newlines\fR to force perltidy to retain all old line break
-points.
-.IP "\fB\-anl\fR, \fB\-\-add\-newlines\fR" 4
-.IX Item "-anl, --add-newlines"
-By default, perltidy will add line breaks when necessary to create
-continuations of long lines and to improve the script appearance. Use
-\&\fB\-nanl\fR or \fB\-\-noadd\-newlines\fR to prevent any new line breaks.
-.Sp
-This flag does not prevent perltidy from eliminating existing line
-breaks; see \fB\-\-freeze\-newlines\fR to completely prevent changes to line
-break points.
-.IP "Controlling whether perltidy breaks before or after operators" 4
-.IX Item "Controlling whether perltidy breaks before or after operators"
-Four command line parameters provide some control over whether
-a line break should be before or after specific token types.
-Two parameters give detailed control:
-.Sp
-\&\fB\-wba=s\fR or \fB\-\-want\-break\-after=s\fR, and
-.Sp
-\&\fB\-wbb=s\fR or \fB\-\-want\-break\-before=s\fR.
-.Sp
-These parameters are each followed by a quoted string, \fBs\fR, containing
-a list of token types (separated only by spaces). No more than one of each
-of these parameters should be specified, because repeating a
-command-line parameter always overwrites the previous one before
-perltidy ever sees it.
-.Sp
-By default, perltidy breaks \fBafter\fR these token types:
- % + \- * / x != == >= <= =~ !~ < > | &
- = **= += *= &= <<= &&= \-= /= |= >>= ||= //= .= %= ^= x=
-.Sp
-And perltidy breaks \fBbefore\fR these token types by default:
- . << >> \-> && || //
-.Sp
-To illustrate, to cause a break after a concatenation operator, \f(CW\*(Aq.\*(Aq\fR,
-rather than before it, the command line would be
-.Sp
-.Vb 1
-\& \-wba="."
-.Ve
-.Sp
-As another example, the following command would cause a break before
-math operators \f(CW\*(Aq+\*(Aq\fR, \f(CW\*(Aq\-\*(Aq\fR, \f(CW\*(Aq/\*(Aq\fR, and \f(CW\*(Aq*\*(Aq\fR:
-.Sp
-.Vb 1
-\& \-wbb="+ \- / *"
-.Ve
-.Sp
-These commands should work well for most of the token types that perltidy uses
-(use \fB\-\-dump\-token\-types\fR for a list). Also try the \fB\-D\fR flag on a short
-snippet of code and look at the .DEBUG file to see the tokenization. However,
-for a few token types there may be conflicts with hardwired logic which cause
-unexpected results. One example is curly braces, which should be controlled
-with the parameter \fBbl\fR provided for that purpose.
-.Sp
-\&\fB\s-1WARNING\s0\fR Be sure to put these tokens in quotes to avoid having them
-misinterpreted by your command shell.
-.Sp
-Two additional parameters are available which, though they provide no further
-capability, can simplify input are:
-.Sp
-\&\fB\-baao\fR or \fB\-\-break\-after\-all\-operators\fR,
-.Sp
-\&\fB\-bbao\fR or \fB\-\-break\-before\-all\-operators\fR.
-.Sp
-The \-baao sets the default to be to break after all of the following operators:
-.Sp
-.Vb 3
-\& % + \- * / x != == >= <= =~ !~ < > | &
-\& = **= += *= &= <<= &&= \-= /= |= >>= ||= //= .= %= ^= x=
-\& . : ? && || and or err xor
-.Ve
-.Sp
-and the \fB\-bbao\fR flag sets the default to break before all of these operators.
-These can be used to define an initial break preference which can be fine-tuned
-with the \fB\-wba\fR and \fB\-wbb\fR flags. For example, to break before all operators
-except an \fB=\fR one could use \-\-bbao \-wba='=' rather than listing every
-single perl operator except \fB=\fR on a \-wbb flag.
-.SS "Controlling List Formatting"
-.IX Subsection "Controlling List Formatting"
-Perltidy attempts to place comma-separated arrays of values in tables
-which look good. Its default algorithms usually work well, and they
-have been improving with each release, but several parameters are
-available to control list formatting.
-.IP "\fB\-boc\fR, \fB\-\-break\-at\-old\-comma\-breakpoints\fR" 4
-.IX Item "-boc, --break-at-old-comma-breakpoints"
-This flag tells perltidy to try to break at all old commas. This is not
-the default. Normally, perltidy makes a best guess at list formatting,
-and seldom uses old comma breakpoints. Usually this works well,
-but consider:
-.Sp
-.Vb 5
-\& my @list = (1,
-\& 1, 1,
-\& 1, 2, 1,
-\& 1, 3, 3, 1,
-\& 1, 4, 6, 4, 1,);
-.Ve
-.Sp
-The default formatting will flatten this down to one line:
-.Sp
-.Vb 2
-\& # perltidy (default)
-\& my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
-.Ve
-.Sp
-which hides the structure. Using \fB\-boc\fR, plus additional flags
-to retain the original style, yields
-.Sp
-.Vb 6
-\& # perltidy \-boc \-lp \-pt=2 \-vt=1 \-vtc=1
-\& my @list = (1,
-\& 1, 1,
-\& 1, 2, 1,
-\& 1, 3, 3, 1,
-\& 1, 4, 6, 4, 1,);
-.Ve
-.Sp
-A disadvantage of this flag is that all tables in the file
-must already be nicely formatted. For another possibility see
-the \-fs flag in \*(L"Skipping Selected Sections of Code\*(R".
-.IP "\fB\-mft=n\fR, \fB\-\-maximum\-fields\-per\-table=n\fR" 4
-.IX Item "-mft=n, --maximum-fields-per-table=n"
-If the computed number of fields for any table exceeds \fBn\fR, then it
-will be reduced to \fBn\fR. The default value for \fBn\fR is a large number,
-40. While this value should probably be left unchanged as a general
-rule, it might be used on a small section of code to force a list to
-have a particular number of fields per line, and then either the \fB\-boc\fR
-flag could be used to retain this formatting, or a single comment could
-be introduced somewhere to freeze the formatting in future applications
-of perltidy.
-.Sp
-.Vb 9
-\& # perltidy \-mft=2
-\& @month_of_year = (
-\& \*(AqJan\*(Aq, \*(AqFeb\*(Aq,
-\& \*(AqMar\*(Aq, \*(AqApr\*(Aq,
-\& \*(AqMay\*(Aq, \*(AqJun\*(Aq,
-\& \*(AqJul\*(Aq, \*(AqAug\*(Aq,
-\& \*(AqSep\*(Aq, \*(AqOct\*(Aq,
-\& \*(AqNov\*(Aq, \*(AqDec\*(Aq
-\& );
-.Ve
-.IP "\fB\-cab=n\fR, \fB\-\-comma\-arrow\-breakpoints=n\fR" 4
-.IX Item "-cab=n, --comma-arrow-breakpoints=n"
-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 \fB\-boc\fR is used). The possible values of \fBn\fR are:
-.Sp
-.Vb 10
-\& n=0 break at all commas after =>
-\& 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)
-.Ve
-.Sp
-For example, given the following single line, perltidy by default will
-not add any line breaks because it would break the existing one-line
-container:
-.Sp
-.Vb 1
-\& bless { B => $B, Root => $Root } => $package;
-.Ve
-.Sp
-Using \fB\-cab=0\fR will force a break after each comma-arrow item:
-.Sp
-.Vb 5
-\& # perltidy \-cab=0:
-\& bless {
-\& B => $B,
-\& Root => $Root
-\& } => $package;
-.Ve
-.Sp
-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 \fB\-cab=2\fR could
-be used.
-.Sp
-The flag \fB\-cab=3\fR can be used to prevent these commas from being
-treated specially. In this case, an item such as \*(L"01\*(R" => 31 is
-treated as a single item in a table. The number of fields in this table
-will be determined by the same rules that are used for any other table.
-Here is an example.
-.Sp
-.Vb 6
-\& # perltidy \-cab=3
-\& my %last_day = (
-\& "01" => 31, "02" => 29, "03" => 31, "04" => 30,
-\& "05" => 31, "06" => 30, "07" => 31, "08" => 31,
-\& "09" => 30, "10" => 31, "11" => 30, "12" => 31
-\& );
-.Ve
-.SS "Retaining or Ignoring Existing Line Breaks"
-.IX Subsection "Retaining or Ignoring Existing Line Breaks"
-Several additional parameters are available for controlling the extent
-to which line breaks in the input script influence the output script.
-In most cases, the default parameter values are set so that, if a choice
-is possible, the output style follows the input style. For example, if
-a short logical container is broken in the input script, then the
-default behavior is for it to remain broken in the output script.
-.PP
-Most of the parameters in this section would only be required for a
-one-time conversion of a script from short container lengths to longer
-container lengths. The opposite effect, of converting long container
-lengths to shorter lengths, can be obtained by temporarily using a short
-maximum line length.
-.IP "\fB\-bol\fR, \fB\-\-break\-at\-old\-logical\-breakpoints\fR" 4
-.IX Item "-bol, --break-at-old-logical-breakpoints"
-By default, if a logical expression is broken at a \f(CW\*(C`&&\*(C'\fR, \f(CW\*(C`||\*(C'\fR, \f(CW\*(C`and\*(C'\fR,
-or \f(CW\*(C`or\*(C'\fR, then the container will remain broken. Also, breaks
-at internal keywords \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`unless\*(C'\fR will normally be retained.
-To prevent this, and thus form longer lines, use \fB\-nbol\fR.
-.IP "\fB\-bok\fR, \fB\-\-break\-at\-old\-keyword\-breakpoints\fR" 4
-.IX Item "-bok, --break-at-old-keyword-breakpoints"
-By default, perltidy will retain a breakpoint before keywords which may
-return lists, such as \f(CW\*(C`sort\*(C'\fR and <map>. This allows chains of these
-operators to be displayed one per line. Use \fB\-nbok\fR to prevent
-retaining these breakpoints.
-.IP "\fB\-bot\fR, \fB\-\-break\-at\-old\-ternary\-breakpoints\fR" 4
-.IX Item "-bot, --break-at-old-ternary-breakpoints"
-By default, if a conditional (ternary) operator is broken at a \f(CW\*(C`:\*(C'\fR,
-then it will remain broken. To prevent this, and thereby
-form longer lines, use \fB\-nbot\fR.
-.IP "\fB\-boa\fR, \fB\-\-break\-at\-old\-attribute\-breakpoints\fR" 4
-.IX Item "-boa, --break-at-old-attribute-breakpoints"
-By default, if an attribute list is broken at a \f(CW\*(C`:\*(C'\fR in the source file, then
-it will remain broken. For example, given the following code, the line breaks
-at the ':'s will be retained:
-.Sp
-.Vb 4
-\& my @field
-\& : field
-\& : Default(1)
-\& : Get(\*(AqName\*(Aq => \*(Aqfoo\*(Aq) : Set(\*(AqName\*(Aq);
-.Ve
-.Sp
-If the attributes are on a single line in the source code then they will remain
-on a single line if possible.
-.Sp
-To prevent this, and thereby always form longer lines, use \fB\-nboa\fR.
-.IP "\fB\-iob\fR, \fB\-\-ignore\-old\-breakpoints\fR" 4
-.IX Item "-iob, --ignore-old-breakpoints"
-Use this flag to tell perltidy to ignore existing line breaks to the
-maximum extent possible. This will tend to produce the longest possible
-containers, regardless of type, which do not exceed the line length
-limit.
-.IP "\fB\-kis\fR, \fB\-\-keep\-interior\-semicolons\fR" 4
-.IX Item "-kis, --keep-interior-semicolons"
-Use the \fB\-kis\fR flag to prevent breaking at a semicolon if
-there was no break there in the input file. Normally
-perltidy places a newline after each semicolon which
-terminates a statement unless several statements are
-contained within a one-line brace block. To illustrate,
-consider the following input lines:
-.Sp
-.Vb 2
-\& dbmclose(%verb_delim); undef %verb_delim;
-\& dbmclose(%expanded); undef %expanded;
-.Ve
-.Sp
-The default is to break after each statement, giving
-.Sp
-.Vb 4
-\& dbmclose(%verb_delim);
-\& undef %verb_delim;
-\& dbmclose(%expanded);
-\& undef %expanded;
-.Ve
-.Sp
-With \fBperltidy \-kis\fR the multiple statements are retained:
-.Sp
-.Vb 2
-\& dbmclose(%verb_delim); undef %verb_delim;
-\& dbmclose(%expanded); undef %expanded;
-.Ve
-.Sp
-The statements are still subject to the specified value
-of \fBmaximum-line-length\fR and will be broken if this
-maximum is exceeded.
-.SS "Blank Line Control"
-.IX Subsection "Blank Line Control"
-Blank lines can improve the readability of a script if they are carefully
-placed. Perltidy has several commands for controlling the insertion,
-retention, and removal of blank lines.
-.IP "\fB\-fbl\fR, \fB\-\-freeze\-blank\-lines\fR" 4
-.IX Item "-fbl, --freeze-blank-lines"
-Set \fB\-fbl\fR if you want to the blank lines in your script to
-remain exactly as they are. The rest of the parameters in
-this section may then be ignored. (Note: setting the \fB\-fbl\fR flag
-is equivalent to setting \fB\-mbl=0\fR and \fB\-kbl=2\fR).
-.IP "\fB\-bbc\fR, \fB\-\-blanks\-before\-comments\fR" 4
-.IX Item "-bbc, --blanks-before-comments"
-A blank line will be introduced before a full-line comment. This is the
-default. Use \fB\-nbbc\fR or \fB\-\-noblanks\-before\-comments\fR to prevent
-such blank lines from being introduced.
-.IP "\fB\-blbs=n\fR, \fB\-\-blank\-lines\-before\-subs=n\fR" 4
-.IX Item "-blbs=n, --blank-lines-before-subs=n"
-The parameter \fB\-blbs=n\fR requests that least \fBn\fR 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>. \fB\s-1BEGIN\s0\fR and \fB\s-1END\s0\fR blocks are included.
-.Sp
-The requested number of blanks statement will be inserted regardless of the
-value of \fB\-\-maximum\-consecutive\-blank\-lines=n\fR (\fB\-mbl=n\fR) with the exception
-that if \fB\-mbl=0\fR then no blanks will be output.
-.Sp
-This parameter interacts with the value \fBk\fR of the parameter \fB\-\-maximum\-consecutive\-blank\-lines=k\fR (\fB\-mbl=k\fR) as follows:
-.Sp
-1. If \fB\-mbl=0\fR then no blanks will be output. This allows all blanks to be suppressed with a single parameter. Otherwise,
-.Sp
-2. If the number of old blank lines in the script is less than \fBn\fR then
-additional blanks will be inserted to make the total \fBn\fR regardless of the
-value of \fB\-mbl=k\fR.
-.Sp
-3. If the number of old blank lines in the script equals or exceeds \fBn\fR then
-this parameter has no effect, however the total will not exceed
-value specified on the \fB\-mbl=k\fR flag.
-.IP "\fB\-blbp=n\fR, \fB\-\-blank\-lines\-before\-packages=n\fR" 4
-.IX Item "-blbp=n, --blank-lines-before-packages=n"
-The parameter \fB\-blbp=n\fR requests that least \fBn\fR blank lines precede a package
-which does not follow a comment. The default is \fB\-blbp=1\fR.
-.Sp
-This parameter interacts with the value \fBk\fR of the parameter
-\&\fB\-\-maximum\-consecutive\-blank\-lines=k\fR (\fB\-mbl=k\fR) in the same way as described
-for the previous item \fB\-blbs=n\fR.
-.IP "\fB\-bbs\fR, \fB\-\-blanks\-before\-subs\fR" 4
-.IX Item "-bbs, --blanks-before-subs"
-For compatibility with previous versions, \fB\-bbs\fR or \fB\-\-blanks\-before\-subs\fR
-is equivalent to \fI\-blbp=1\fR and \fI\-blbs=1\fR.
-.Sp
-Likewise, \fB\-nbbs\fR or \fB\-\-noblanks\-before\-subs\fR
-is equivalent to \fI\-blbp=0\fR and \fI\-blbs=0\fR.
-.IP "\fB\-bbb\fR, \fB\-\-blanks\-before\-blocks\fR" 4
-.IX Item "-bbb, --blanks-before-blocks"
-A blank line will be introduced before blocks of coding delimited by
-\&\fBfor\fR, \fBforeach\fR, \fBwhile\fR, \fBuntil\fR, and \fBif\fR, \fBunless\fR, in the following
-circumstances:
-.RS 4
-.IP "\(bu" 4
-The block is not preceded by a comment.
-.IP "\(bu" 4
-The block is not a one-line block.
-.IP "\(bu" 4
-The number of consecutive non-blank lines at the current indentation depth is at least \fB\-lbl\fR
-(see next section).
-.RE
-.RS 4
-.Sp
-This is the default. The intention of this option is to introduce
-some space within dense coding.
-This is negated with \fB\-nbbb\fR or \fB\-\-noblanks\-before\-blocks\fR.
-.RE
-.IP "\fB\-lbl=n\fR \fB\-\-long\-block\-line\-count=n\fR" 4
-.IX Item "-lbl=n --long-block-line-count=n"
-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 \fB0\fR is equivalent to entering a very large number.
-.IP "\fB\-blao=i\fR or \fB\-\-blank\-lines\-after\-opening\-block=i\fR" 4
-.IX Item "-blao=i or --blank-lines-after-opening-block=i"
-This control places a minimum of \fBi\fR blank lines \fBafter\fR a line which \fBends\fR
-with an opening block brace of a specified type. By default, this only applies
-to the block of a named \fBsub\fR, but this can be changed (see \fB\-blaol\fR below).
-The default is not to do this (\fBi=0\fR).
-.Sp
-Please see the note below on using the \fB\-blao\fR and \fB\-blbc\fR options.
-.IP "\fB\-blbc=i\fR or \fB\-\-blank\-lines\-before\-closing\-block=i\fR" 4
-.IX Item "-blbc=i or --blank-lines-before-closing-block=i"
-This control places a minimum of \fBi\fR blank lines \fBbefore\fR a line which
-\&\fBbegins\fR with a closing block brace of a specified type. By default, this
-only applies to the block of a named \fBsub\fR, but this can be changed (see
-\&\fB\-blbcl\fR below). The default is not to do this (\fBi=0\fR).
-.IP "\fB\-blaol=s\fR or \fB\-\-blank\-lines\-after\-opening\-block\-list=s\fR" 4
-.IX Item "-blaol=s or --blank-lines-after-opening-block-list=s"
-The parameter \fBs\fR is a list of block type keywords to which the flag \fB\-blao\fR
-should apply. The section \*(L"Specifying Block Types\*(R" explains how to list
-block types.
-.IP "\fB\-blbcl=s\fR or \fB\-\-blank\-lines\-before\-closing\-block\-list=s\fR" 4
-.IX Item "-blbcl=s or --blank-lines-before-closing-block-list=s"
-This parameter is a list of block type keywords to which the flag \fB\-blbc\fR
-should apply. The section \*(L"Specifying Block Types\*(R" explains how to list
-block types.
-.IP "Note on using the \fB\-blao\fR and \fB\-blbc\fR options." 4
-.IX Item "Note on using the -blao and -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.
-.Sp
-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
-.Sp
-.Vb 1
-\& perltidy \-blao=2 \-blbc=2 \-blaol=\*(Aq*\*(Aq \-blbcl=\*(Aq*\*(Aq filename
-.Ve
-.Sp
-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 \fB\-blao=0\fR and \fB\-blbc=0\fR will undo them. However, by default
-perltidy retains single blank lines, so the blank lines remain.
-.Sp
-We can easily fix this by telling perltidy to ignore old blank lines by
-including the added parameter \fB\-kbl=0\fR 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.
-.IP "\fB\-mbl=n\fR \fB\-\-maximum\-consecutive\-blank\-lines=n\fR" 4
-.IX Item "-mbl=n --maximum-consecutive-blank-lines=n"
-This parameter specifies the maximum number of consecutive blank lines which
-will be output within code sections of a script. The default is n=1. If the
-input file has more than n consecutive blank lines, the number will be reduced
-to n except as noted above for the \fB\-blbp\fR and \fB\-blbs\fR parameters. If \fBn=0\fR
-then no blank lines will be output (unless all old blank lines are retained
-with the \fB\-kbl=2\fR flag of the next section).
-.Sp
-This flag obviously does not apply to pod sections,
-here-documents, and quotes.
-.IP "\fB\-kbl=n\fR, \fB\-\-keep\-old\-blank\-lines=n\fR" 4
-.IX Item "-kbl=n, --keep-old-blank-lines=n"
-The \fB\-kbl=n\fR flag gives you control over how your existing blank lines are
-treated.
-.Sp
-The possible values of \fBn\fR are:
-.Sp
-.Vb 3
-\& n=0 ignore all old blank lines
-\& n=1 stable: keep old blanks, but limited by the value of the B<\-mbl=n> flag
-\& n=2 keep all old blank lines, regardless of the value of the B<\-mbl=n> flag
-.Ve
-.Sp
-The default is \fBn=1\fR.
-.IP "\fB\-sob\fR, \fB\-\-swallow\-optional\-blank\-lines\fR" 4
-.IX Item "-sob, --swallow-optional-blank-lines"
-This is equivalent to \fBkbl=0\fR and is included for compatibility with
-previous versions.
-.IP "\fB\-nsob\fR, \fB\-\-noswallow\-optional\-blank\-lines\fR" 4
-.IX Item "-nsob, --noswallow-optional-blank-lines"
-This is equivalent to \fBkbl=1\fR and is included for compatibility with
-previous versions.
-.SS "Styles"
-.IX Subsection "Styles"
-A style refers to a convenient collection of existing parameters.
-.IP "\fB\-gnu\fR, \fB\-\-gnu\-style\fR" 4
-.IX Item "-gnu, --gnu-style"
-\&\fB\-gnu\fR gives an approximation to the \s-1GNU\s0 Coding Standards (which do
-not apply to perl) as they are sometimes implemented. At present, this
-style overrides the default style with the following parameters:
-.Sp
-.Vb 1
-\& \-lp \-bl \-noll \-pt=2 \-bt=2 \-sbt=2 \-icp
-.Ve
-.IP "\fB\-pbp\fR, \fB\-\-perl\-best\-practices\fR" 4
-.IX Item "-pbp, --perl-best-practices"
-\&\fB\-pbp\fR is an abbreviation for the parameters in the book \fBPerl Best Practices\fR
-by Damian Conway:
-.Sp
-.Vb 3
-\& \-l=78 \-i=4 \-ci=4 \-st \-se \-vt=2 \-cti=0 \-pt=1 \-bt=1 \-sbt=1 \-bbt=1 \-nsfs \-nolq
-\& \-wbb="% + \- * / x != == >= <= =~ !~ < > | & =
-\& **= += *= &= <<= &&= \-= /= |= >>= ||= //= .= %= ^= x="
-.Ve
-.Sp
-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
-\&\fB\-nst\fR and/or \fB\-nse\fR after the \-pbp parameter.
-.Sp
-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,
-.Sp
-.Vb 11
-\& # perltidy \-pbp
-\& $self\->{_text} = (
-\& !$section ? \*(Aq\*(Aq
-\& : $type eq \*(Aqitem\*(Aq ? "the $section entry"
-\& : "the section on $section"
-\& )
-\& . (
-\& $page
-\& ? ( $section ? \*(Aq in \*(Aq : \*(Aq\*(Aq ) . "the $page$page_ext manpage"
-\& : \*(Aq elsewhere in this document\*(Aq
-\& );
-\&
-\& # perltidy \-pbp \-ci=2
-\& $self\->{_text} = (
-\& !$section ? \*(Aq\*(Aq
-\& : $type eq \*(Aqitem\*(Aq ? "the $section entry"
-\& : "the section on $section"
-\& )
-\& . (
-\& $page
-\& ? ( $section ? \*(Aq in \*(Aq : \*(Aq\*(Aq ) . "the $page$page_ext manpage"
-\& : \*(Aq elsewhere in this document\*(Aq
-\& );
-.Ve
-.SS "Controlling Vertical Alignment"
-.IX Subsection "Controlling Vertical Alignment"
-Vertical alignment refers to lining up certain symbols in list of consecutive
-similar lines to improve readability. For example, the \*(L"fat commas\*(R" are
-aligned in the following statement:
-.PP
-.Vb 5
-\& $data = $pkg\->new(
-\& PeerAddr => join( ".", @port[ 0 .. 3 ] ),
-\& PeerPort => $port[4] * 256 + $port[5],
-\& Proto => \*(Aqtcp\*(Aq
-\& );
-.Ve
-.PP
-The only explicit control on vertical alignment is to turn it off using
-\&\fB\-novalign\fR, a flag mainly intended for debugging. 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.
-.PP
-.Vb 4
-\& %option_range = (
-\& \*(Aqformat\*(Aq => [ \*(Aqtidy\*(Aq, \*(Aqhtml\*(Aq, \*(Aquser\*(Aq ],
-\& \*(Aqoutput\-line\-ending\*(Aq => [ \*(Aqdos\*(Aq, \*(Aqwin\*(Aq, \*(Aqmac\*(Aq, \*(Aqunix\*(Aq ],
-\& \*(Aqcharacter\-encoding\*(Aq => [ \*(Aqnone\*(Aq, \*(Aqutf8\*(Aq ],
-\&
-\& \*(Aqblock\-brace\-tightness\*(Aq => [ 0, 2 ],
-\& \*(Aqbrace\-tightness\*(Aq => [ 0, 2 ],
-\& \*(Aqparen\-tightness\*(Aq => [ 0, 2 ],
-\& \*(Aqsquare\-bracket\-tightness\*(Aq => [ 0, 2 ],
-\& );
-.Ve
-.SS "Other Controls"
-.IX Subsection "Other Controls"
-.IP "Deleting selected text" 4
-.IX Item "Deleting selected text"
-Perltidy can selectively delete comments and/or pod documentation. The
-command \fB\-dac\fR or \fB\-\-delete\-all\-comments\fR will delete all comments
-\&\fBand\fR all pod documentation, leaving just code and any leading system
-control lines.
-.Sp
-The command \fB\-dp\fR or \fB\-\-delete\-pod\fR will remove all pod documentation
-(but not comments).
-.Sp
-Two commands which remove comments (but not pod) are: \fB\-dbc\fR or
-\&\fB\-\-delete\-block\-comments\fR and \fB\-dsc\fR or \fB\-\-delete\-side\-comments\fR.
-(Hanging side comments will be deleted with block comments here.)
-.Sp
-The negatives of these commands also work, and are the defaults. When
-block comments are deleted, any leading 'hash\-bang' will be retained.
-Also, if the \fB\-x\fR flag is used, any system commands before a leading
-hash-bang will be retained (even if they are in the form of comments).
-.IP "Writing selected text to a file" 4
-.IX Item "Writing selected text to a file"
-When perltidy writes a formatted text file, it has the ability to also
-send selected text to a file with a \fI.TEE\fR extension. This text can
-include comments and pod documentation.
-.Sp
-The command \fB\-tac\fR or \fB\-\-tee\-all\-comments\fR will write all comments
-\&\fBand\fR all pod documentation.
-.Sp
-The command \fB\-tp\fR or \fB\-\-tee\-pod\fR will write all pod documentation (but
-not comments).
-.Sp
-The commands which write comments (but not pod) are: \fB\-tbc\fR or
-\&\fB\-\-tee\-block\-comments\fR and \fB\-tsc\fR or \fB\-\-tee\-side\-comments\fR.
-(Hanging side comments will be written with block comments here.)
-.Sp
-The negatives of these commands also work, and are the defaults.
-.IP "Using a \fI.perltidyrc\fR command file" 4
-.IX Item "Using a .perltidyrc command file"
-If you use perltidy frequently, you probably won't be happy until you
-create a \fI.perltidyrc\fR file to avoid typing commonly-used parameters.
-Perltidy will first look in your current directory for a command file
-named \fI.perltidyrc\fR. If it does not find one, it will continue looking
-for one in other standard locations.
-.Sp
-These other locations are system-dependent, and may be displayed with
-the command \f(CW\*(C`perltidy \-dpro\*(C'\fR. Under Unix systems, it will first look
-for an environment variable \fB\s-1PERLTIDY\s0\fR. Then it will look for a
-\&\fI.perltidyrc\fR file in the home directory, and then for a system-wide
-file \fI/usr/local/etc/perltidyrc\fR, and then it will look for
-\&\fI/etc/perltidyrc\fR. Note that these last two system-wide files do not
-have a leading dot. Further system-dependent information will be found
-in the \s-1INSTALL\s0 file distributed with perltidy.
-.Sp
-Under Windows, perltidy will also search for a configuration file named perltidy.ini since Windows does not allow files with a leading period (.).
-Use \f(CW\*(C`perltidy \-dpro\*(C'\fR to see the possible locations for your system.
-An example might be \fIC:\eDocuments and Settings\eAll Users\eperltidy.ini\fR.
-.Sp
-Another option is the use of the \s-1PERLTIDY\s0 environment variable.
-The method for setting environment variables depends upon the version of
-Windows that you are using. Instructions for Windows 95 and later versions can
-be found here:
-.Sp
-http://www.netmanage.com/000/20021101_005_tcm21\-6336.pdf
-.Sp
-Under Windows \s-1NT / 2000 / XP\s0 the \s-1PERLTIDY\s0 environment variable can be placed in
-either the user section or the system section. The later makes the
-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:\eDocuments and Settings\eperltidy.ini
-.Sp
-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
-also be a space before the # for side comments. It is a good idea to
-put complex parameters in either single or double quotes.
-.Sp
-Here is an example of a \fI.perltidyrc\fR file:
-.Sp
-.Vb 8
-\& # This is a simple of a .perltidyrc configuration file
-\& # This implements a highly spaced style
-\& \-se # errors to standard error output
-\& \-w # show all warnings
-\& \-bl # braces on new lines
-\& \-pt=0 # parens not tight at all
-\& \-bt=0 # braces not tight
-\& \-sbt=0 # square brackets not tight
-.Ve
-.Sp
-The parameters in the \fI.perltidyrc\fR file are installed first, so any
-parameters given on the command line will have priority over them.
-.Sp
-To avoid confusion, perltidy ignores any command in the .perltidyrc
-file which would cause some kind of dump and an exit. These are:
-.Sp
-.Vb 1
-\& \-h \-v \-ddf \-dln \-dop \-dsn \-dtt \-dwls \-dwrs \-ss
-.Ve
-.Sp
-There are several options may be helpful in debugging a \fI.perltidyrc\fR
-file:
-.RS 4
-.IP "\(bu" 4
-A very helpful command is \fB\-\-dump\-profile\fR or \fB\-dpro\fR. It writes a
-list of all configuration filenames tested to standard output, and
-if a file is found, it dumps the content to standard output before
-exiting. So, to find out where perltidy looks for its configuration
-files, and which one if any it selects, just enter
-.Sp
-.Vb 1
-\& perltidy \-dpro
-.Ve
-.IP "\(bu" 4
-It may be simplest to develop and test configuration files with
-alternative names, and invoke them with \fB\-pro=filename\fR on the command
-line. Then rename the desired file to \fI.perltidyrc\fR when finished.
-.IP "\(bu" 4
-The parameters in the \fI.perltidyrc\fR file can be switched off with
-the \fB\-npro\fR option.
-.IP "\(bu" 4
-The commands \fB\-\-dump\-options\fR, \fB\-\-dump\-defaults\fR, \fB\-\-dump\-long\-names\fR,
-and \fB\-\-dump\-short\-names\fR, all described below, may all be helpful.
-.RE
-.RS 4
-.RE
-.IP "Creating a new abbreviation" 4
-.IX Item "Creating a new abbreviation"
-A special notation is available for use in a \fI.perltidyrc\fR file
-for creating an abbreviation for a group
-of options. This can be used to create a
-shorthand for one or more styles which are frequently, but not always,
-used. The notation is to group the options within curly braces which
-are preceded by the name of the alias (without leading dashes), like this:
-.Sp
-.Vb 4
-\& newword {
-\& \-opt1
-\& \-opt2
-\& }
-.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 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
-.Sp
-.Vb 1
-\& airy {\-bl \-pt=0 \-bt=0 \-sbt=0}
-.Ve
-.Sp
-could be placed in a \fI.perltidyrc\fR file, and then invoked at will with
-.Sp
-.Vb 1
-\& perltidy \-airy somefile.pl
-.Ve
-.Sp
-(Either \f(CW\*(C`\-airy\*(C'\fR or \f(CW\*(C`\-\-airy\*(C'\fR may be used).
-.IP "Skipping leading non-perl commands with \fB\-x\fR or \fB\-\-look\-for\-hash\-bang\fR" 4
-.IX Item "Skipping leading non-perl commands with -x or --look-for-hash-bang"
-If your script has leading lines of system commands or other text which
-are not valid perl code, and which are separated from the start of the
-perl code by a \*(L"hash-bang\*(R" line, ( a line of the form \f(CW\*(C`#!...perl\*(C'\fR ),
-you must use the \fB\-x\fR flag to tell perltidy not to parse and format any
-lines before the \*(L"hash-bang\*(R" line. This option also invokes perl with a
-\&\-x flag when checking the syntax. This option was originally added to
-allow perltidy to parse interactive \s-1VMS\s0 scripts, but it should be used
-for any script which is normally invoked with \f(CW\*(C`perl \-x\*(C'\fR.
-.IP "Making a file unreadable" 4
-.IX Item "Making a file unreadable"
-The goal of perltidy is to improve the readability of files, but there
-are two commands which have the opposite effect, \fB\-\-mangle\fR and
-\&\fB\-\-extrude\fR. They are actually
-merely aliases for combinations of other parameters. Both of these
-strip all possible whitespace, but leave comments and pod documents,
-so that they are essentially reversible. The
-difference between these is that \fB\-\-mangle\fR puts the fewest possible
-line breaks in a script while \fB\-\-extrude\fR puts the maximum possible.
-Note that these options do not provided any meaningful obfuscation, because
-perltidy can be used to reformat the files. They were originally
-developed to help test the tokenization logic of perltidy, but they
-have other uses.
-One use for \fB\-\-mangle\fR is the following:
-.Sp
-.Vb 1
-\& perltidy \-\-mangle myfile.pl \-st | perltidy \-o myfile.pl.new
-.Ve
-.Sp
-This will form the maximum possible number of one-line blocks (see next
-section), and can sometimes help clean up a badly formatted script.
-.Sp
-A similar technique can be used with \fB\-\-extrude\fR instead of \fB\-\-mangle\fR
-to make the minimum number of one-line blocks.
-.Sp
-Another use for \fB\-\-mangle\fR is to combine it with \fB\-dac\fR to reduce
-the file size of a perl script.
-.IP "One-line blocks" 4
-.IX Item "One-line blocks"
-There are a few points to note regarding one-line blocks. A one-line
-block is something like this,
-.Sp
-.Vb 1
-\& if ($x > 0) { $y = 1 / $x }
-.Ve
-.Sp
-where the contents within the curly braces is short enough to fit
-on a single line.
-.Sp
-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.
-.Sp
-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 \fB\-nasc\fR
-option is used) if the block is a code block.
-.Sp
-The main exception is that perltidy will attempt to form new one-line
-blocks following the keywords \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`eval\*(C'\fR, and \f(CW\*(C`sort\*(C'\fR, because
-these code blocks are often small and most clearly displayed in a single
-line.
-.Sp
-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.
-.Sp
-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.
-.IP "Debugging" 4
-.IX Item "Debugging"
-The following flags are available for debugging:
-.Sp
-\&\fB\-\-dump\-cuddled\-block\-list\fR or \fB\-dcbl\fR will dump to standard output the
-internal hash of cuddled block types created by a \fB\-cuddled\-block\-list\fR input
-string.
-.Sp
-\&\fB\-\-dump\-defaults\fR or \fB\-ddf\fR will write the default option set to standard output and quit
-.Sp
-\&\fB\-\-dump\-profile\fR or \fB\-dpro\fR will write the name of the current
-configuration file and its contents to standard output and quit.
-.Sp
-\&\fB\-\-dump\-options\fR or \fB\-dop\fR will write current option set to standard
-output and quit.
-.Sp
-\&\fB\-\-dump\-long\-names\fR or \fB\-dln\fR will write all command line long names (passed
-to Get_options) to standard output and quit.
-.Sp
-\&\fB\-\-dump\-short\-names\fR or \fB\-dsn\fR will write all command line short names
-to standard output and quit.
-.Sp
-\&\fB\-\-dump\-token\-types\fR or \fB\-dtt\fR will write a list of all token types
-to standard output and quit.
-.Sp
-\&\fB\-\-dump\-want\-left\-space\fR or \fB\-dwls\fR will write the hash \f(CW%want_left_space\fR
-to standard output and quit. See the section on controlling whitespace
-around tokens.
-.Sp
-\&\fB\-\-dump\-want\-right\-space\fR or \fB\-dwrs\fR will write the hash \f(CW%want_right_space\fR
-to standard output and quit. See the section on controlling whitespace
-around tokens.
-.Sp
-\&\fB\-\-no\-memoize\fR or \fB\-nmem\fR 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 \fB\-nmem\fR.
-.Sp
-\&\fB\-\-file\-size\-order\fR or \fB\-fso\fR will cause files to be processed in order of
-increasing size, when multiple files are being processed. This is useful
-during program development, when large numbers of files with varying sizes are
-processed, because it can reduce virtual memory usage.
-.Sp
-\&\fB\-DEBUG\fR will write a file with extension \fI.DEBUG\fR for each input file
-showing the tokenization of all lines of code.
-.IP "Working with MakeMaker, AutoLoader and SelfLoader" 4
-.IX Item "Working with MakeMaker, AutoLoader and SelfLoader"
-The first \f(CW$VERSION\fR line of a file which might be eval'd by MakeMaker
-is passed through unchanged except for indentation.
-Use \fB\-\-nopass\-version\-line\fR, or \fB\-npvl\fR, to deactivate this feature.
-.Sp
-If the AutoLoader module is used, perltidy will continue formatting
-code after seeing an _\|_END_\|_ line.
-Use \fB\-\-nolook\-for\-autoloader\fR, or \fB\-nlal\fR, to deactivate this feature.
-.Sp
-Likewise, if the SelfLoader module is used, perltidy will continue formatting
-code after seeing a _\|_DATA_\|_ line.
-Use \fB\-\-nolook\-for\-selfloader\fR, or \fB\-nlsl\fR, to deactivate this feature.
-.IP "Working around problems with older version of Perl" 4
-.IX Item "Working around problems with older version of Perl"
-Perltidy contains a number of rules which help avoid known subtleties
-and problems with older versions of perl, and these rules always
-take priority over whatever formatting flags have been set. For example,
-perltidy will usually avoid starting a new line with a bareword, because
-this might cause problems if \f(CW\*(C`use strict\*(C'\fR is active.
-.Sp
-There is no way to override these rules.
-.SH "HTML OPTIONS"
-.IX Header "HTML OPTIONS"
-.IP "The \fB\-html\fR master switch" 4
-.IX Item "The -html master switch"
-The flag \fB\-html\fR causes perltidy to write an html file with extension
-\&\fI.html\fR. So, for example, the following command
-.Sp
-.Vb 1
-\& perltidy \-html somefile.pl
-.Ve
-.Sp
-will produce a syntax-colored html file named \fIsomefile.pl.html\fR
-which may be viewed with a browser.
-.Sp
-\&\fBPlease Note\fR: In this case, perltidy does not do any formatting to the
-input file, and it does not write a formatted file with extension
-\&\fI.tdy\fR. This means that two perltidy runs are required to create a
-fully reformatted, html copy of a script.
-.IP "The \fB\-pre\fR flag for code snippets" 4
-.IX Item "The -pre flag for code snippets"
-When the \fB\-pre\fR flag is given, only the pre-formatted section, within
-the <\s-1PRE\s0> and </PRE> tags, will be output. This simplifies inclusion
-of the output in other files. The default is to output a complete
-web page.
-.IP "The \fB\-nnn\fR flag for line numbering" 4
-.IX Item "The -nnn flag for line numbering"
-When the \fB\-nnn\fR flag is given, the output lines will be numbered.
-.IP "The \fB\-toc\fR, or \fB\-\-html\-table\-of\-contents\fR flag" 4
-.IX Item "The -toc, or --html-table-of-contents flag"
-By default, a table of contents to packages and subroutines will be
-written at the start of html output. Use \fB\-ntoc\fR to prevent this.
-This might be useful, for example, for a pod document which contains a
-number of unrelated code snippets. This flag only influences the code
-table of contents; it has no effect on any table of contents produced by
-pod2html (see next item).
-.IP "The \fB\-pod\fR, or \fB\-\-pod2html\fR flag" 4
-.IX Item "The -pod, or --pod2html flag"
-There are two options for formatting pod documentation. The default is
-to pass the pod through the Pod::Html module (which forms the basis of
-the pod2html utility). Any code sections are formatted by perltidy, and
-the results then merged. Note: perltidy creates a temporary file when
-Pod::Html is used; see \*(L"\s-1FILES\*(R"\s0. Also, Pod::Html creates temporary
-files for its cache.
-.Sp
-\&\s-1NOTE:\s0 Perltidy counts the number of \f(CW\*(C`=cut\*(C'\fR lines, and either moves the
-pod text to the top of the html file if there is one \f(CW\*(C`=cut\*(C'\fR, or leaves
-the pod text in its original order (interleaved with code) otherwise.
-.Sp
-Most of the flags accepted by pod2html may be included in the perltidy
-command line, and they will be passed to pod2html. In some cases,
-the flags have a prefix \f(CW\*(C`pod\*(C'\fR to emphasize that they are for the
-pod2html, and this prefix will be removed before they are passed to
-pod2html. The flags which have the additional \f(CW\*(C`pod\*(C'\fR prefix are:
-.Sp
-.Vb 2
-\& \-\-[no]podheader \-\-[no]podindex \-\-[no]podrecurse \-\-[no]podquiet
-\& \-\-[no]podverbose \-\-podflush
-.Ve
-.Sp
-The flags which are unchanged from their use in pod2html are:
-.Sp
-.Vb 2
-\& \-\-backlink=s \-\-cachedir=s \-\-htmlroot=s \-\-libpods=s \-\-title=s
-\& \-\-podpath=s \-\-podroot=s
-.Ve
-.Sp
-where 's' is an appropriate character string. Not all of these flags are
-available in older versions of Pod::Html. See your Pod::Html documentation for
-more information.
-.Sp
-The alternative, indicated with \fB\-npod\fR, is not to use Pod::Html, but
-rather to format pod text in italics (or whatever the stylesheet
-indicates), without special html markup. This is useful, for example,
-if pod is being used as an alternative way to write comments.
-.IP "The \fB\-frm\fR, or \fB\-\-frames\fR flag" 4
-.IX Item "The -frm, or --frames flag"
-By default, a single html output file is produced. This can be changed
-with the \fB\-frm\fR option, which creates a frame holding a table of
-contents in the left panel and the source code in the right side. This
-simplifies code browsing. Assume, for example, that the input file is
-\&\fIMyModule.pm\fR. Then, for default file extension choices, these three
-files will be created:
-.Sp
-.Vb 3
-\& MyModule.pm.html \- the frame
-\& MyModule.pm.toc.html \- the table of contents
-\& MyModule.pm.src.html \- the formatted source code
-.Ve
-.Sp
-Obviously this file naming scheme requires that output be directed to a real
-file (as opposed to, say, standard output). If this is not the
-case, or if the file extension is unknown, the \fB\-frm\fR option will be
-ignored.
-.IP "The \fB\-text=s\fR, or \fB\-\-html\-toc\-extension\fR flag" 4
-.IX Item "The -text=s, or --html-toc-extension flag"
-Use this flag to specify the extra file extension of the table of contents file
-when html frames are used. The default is \*(L"toc\*(R".
-See \*(L"Specifying File Extensions\*(R".
-.IP "The \fB\-sext=s\fR, or \fB\-\-html\-src\-extension\fR flag" 4
-.IX Item "The -sext=s, or --html-src-extension flag"
-Use this flag to specify the extra file extension of the content file when html
-frames are used. The default is \*(L"src\*(R".
-See \*(L"Specifying File Extensions\*(R".
-.IP "The \fB\-hent\fR, or \fB\-\-html\-entities\fR flag" 4
-.IX Item "The -hent, or --html-entities flag"
-This flag controls the use of Html::Entities for html formatting. By
-default, the module Html::Entities is used to encode special symbols.
-This may not be the right thing for some browser/language
-combinations. Use \-\-nohtml\-entities or \-nhent to prevent this.
-.IP "Style Sheets" 4
-.IX Item "Style Sheets"
-Style sheets make it very convenient to control and adjust the
-appearance of html pages. The default behavior is to write a page of
-html with an embedded style sheet.
-.Sp
-An alternative to an embedded style sheet is to create a page with a
-link to an external style sheet. This is indicated with the
-\&\fB\-css=filename\fR, where the external style sheet is \fIfilename\fR. The
-external style sheet \fIfilename\fR will be created if and only if it does
-not exist. This option is useful for controlling multiple pages from a
-single style sheet.
-.Sp
-To cause perltidy to write a style sheet to standard output and exit,
-use the \fB\-ss\fR, or \fB\-\-stylesheet\fR, flag. This is useful if the style
-sheet could not be written for some reason, such as if the \fB\-pre\fR flag
-was used. Thus, for example,
-.Sp
-.Vb 1
-\& perltidy \-html \-ss >mystyle.css
-.Ve
-.Sp
-will write a style sheet with the default properties to file
-\&\fImystyle.css\fR.
-.Sp
-The use of style sheets is encouraged, but a web page without a style
-sheets can be created with the flag \fB\-nss\fR. Use this option if you
-must to be sure that older browsers (roughly speaking, versions prior to
-4.0 of Netscape Navigator and Internet Explorer) can display the
-syntax-coloring of the html files.
-.IP "Controlling \s-1HTML\s0 properties" 4
-.IX Item "Controlling HTML properties"
-Note: It is usually more convenient to accept the default properties
-and then edit the stylesheet which is produced. However, this section
-shows how to control the properties with flags to perltidy.
-.Sp
-Syntax colors may be changed from their default values by flags of the either
-the long form, \fB\-html\-color\-xxxxxx=n\fR, or more conveniently the short form,
-\&\fB\-hcx=n\fR, where \fBxxxxxx\fR is one of the following words, and \fBx\fR is the
-corresponding abbreviation:
-.Sp
-.Vb 10
-\& Token Type xxxxxx x
-\& \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-
-\& comment comment c
-\& number numeric n
-\& identifier identifier i
-\& bareword, function bareword w
-\& keyword keyword k
-\& quite, pattern quote q
-\& here doc text here\-doc\-text h
-\& here doc target here\-doc\-target hh
-\& punctuation punctuation pu
-\& parentheses paren p
-\& structural braces structure s
-\& semicolon semicolon sc
-\& colon colon co
-\& comma comma cm
-\& label label j
-\& sub definition name subroutine m
-\& pod text pod\-text pd
-.Ve
-.Sp
-A default set of colors has been defined, but they may be changed by providing
-values to any of the following parameters, where \fBn\fR is either a 6 digit
-hex \s-1RGB\s0 color value or an ascii name for a color, such as 'red'.
-.Sp
-To illustrate, the following command will produce an html
-file \fIsomefile.pl.html\fR with \*(L"aqua\*(R" keywords:
-.Sp
-.Vb 1
-\& perltidy \-html \-hck=00ffff somefile.pl
-.Ve
-.Sp
-and this should be equivalent for most browsers:
-.Sp
-.Vb 1
-\& perltidy \-html \-hck=aqua somefile.pl
-.Ve
-.Sp
-Perltidy merely writes any non-hex names that it sees in the html file.
-The following 16 color names are defined in the \s-1HTML 3.2\s0 standard:
-.Sp
-.Vb 10
-\& black => 000000,
-\& silver => c0c0c0,
-\& gray => 808080,
-\& white => ffffff,
-\& maroon => 800000,
-\& red => ff0000,
-\& purple => 800080,
-\& fuchsia => ff00ff,
-\& green => 008000,
-\& lime => 00ff00,
-\& olive => 808000,
-\& yellow => ffff00
-\& navy => 000080,
-\& blue => 0000ff,
-\& teal => 008080,
-\& aqua => 00ffff,
-.Ve
-.Sp
-Many more names are supported in specific browsers, but it is safest
-to use the hex codes for other colors. Helpful color tables can be
-located with an internet search for \*(L"\s-1HTML\s0 color tables\*(R".
-.Sp
-Besides color, two other character attributes may be set: bold, and italics.
-To set a token type to use bold, use the flag
-\&\fB\-\-html\-bold\-xxxxxx\fR or \fB\-hbx\fR, where \fBxxxxxx\fR or \fBx\fR are the long
-or short names from the above table. Conversely, to set a token type to
-\&\s-1NOT\s0 use bold, use \fB\-\-nohtml\-bold\-xxxxxx\fR or \fB\-nhbx\fR.
-.Sp
-Likewise, to set a token type to use an italic font, use the flag
-\&\fB\-\-html\-italic\-xxxxxx\fR or \fB\-hix\fR, where again \fBxxxxxx\fR or \fBx\fR are the
-long or short names from the above table. And to set a token type to
-\&\s-1NOT\s0 use italics, use \fB\-\-nohtml\-italic\-xxxxxx\fR or \fB\-nhix\fR.
-.Sp
-For example, to use bold braces and lime color, non-bold, italics keywords the
-following command would be used:
-.Sp
-.Vb 1
-\& perltidy \-html \-hbs \-hck=00FF00 \-nhbk \-hik somefile.pl
-.Ve
-.Sp
-The background color can be specified with \fB\-\-html\-color\-background=n\fR,
-or \fB\-hcbg=n\fR for short, where n is a 6 character hex \s-1RGB\s0 value. The
-default color of text is the value given to \fBpunctuation\fR, which is
-black as a default.
-.Sp
-Here are some notes and hints:
-.Sp
-1. If you find a preferred set of these parameters, you may want
-to create a \fI.perltidyrc\fR file containing them. See the perltidy man
-page for an explanation.
-.Sp
-2. Rather than specifying values for these parameters, it is probably
-easier to accept the defaults and then edit a style sheet. The style
-sheet contains comments which should make this easy.
-.Sp
-3. The syntax-colored html files can be very large, so it may be best to
-split large files into smaller pieces to improve download times.
-.SH "SOME COMMON INPUT CONVENTIONS"
-.IX Header "SOME COMMON INPUT CONVENTIONS"
-.SS "Specifying Block Types"
-.IX Subsection "Specifying Block Types"
-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 \fBif\fR, \fBelse\fR, or \fBsub\fR.
-An exception is a labeled block, which has no keyword, and should be specified
-with just a colon. To specify all blocks use \fB'*'\fR.
-.PP
-The keyword \fBsub\fR indicates a named sub. For anonymous subs, use the special
-keyword \fBasub\fR.
-.PP
-For example, the following parameter specifies \f(CW\*(C`sub\*(C'\fR, labels, \f(CW\*(C`BEGIN\*(C'\fR, and
-\&\f(CW\*(C`END\*(C'\fR blocks:
-.PP
-.Vb 1
-\& \-cscl="sub : BEGIN END"
-.Ve
-.PP
-(the meaning of the \-cscl parameter is described above.) Note that
-quotes are required around the list of block types because of the
-spaces. For another example, the following list specifies all block types
-for vertical tightness:
-.PP
-.Vb 1
-\& \-bbvtl=\*(Aq*\*(Aq
-.Ve
-.SS "Specifying File Extensions"
-.IX Subsection "Specifying File Extensions"
-Several parameters allow default file extensions to be overridden. For
-example, a backup file extension may be specified with \fB\-bext=ext\fR,
-where \fBext\fR is some new extension. In order to provides the user some
-flexibility, the following convention is used in all cases to decide if
-a leading '.' should be used. If the extension \f(CW\*(C`ext\*(C'\fR begins with
-\&\f(CW\*(C`A\-Z\*(C'\fR, \f(CW\*(C`a\-z\*(C'\fR, or \f(CW\*(C`0\-9\*(C'\fR, then it will be appended to the filename with
-an intermediate '.' (or perhaps an '_' on \s-1VMS\s0 systems). Otherwise, it
-will be appended directly.
-.PP
-For example, suppose the file is \fIsomefile.pl\fR. For \f(CW\*(C`\-bext=old\*(C'\fR, a '.' is
-added to give \fIsomefile.pl.old\fR. For \f(CW\*(C`\-bext=.old\*(C'\fR, no additional '.' is
-added, so again the backup file is \fIsomefile.pl.old\fR. For \f(CW\*(C`\-bext=~\*(C'\fR, then no
-dot is added, and the backup file will be \fIsomefile.pl~\fR .
-.SH "SWITCHES WHICH MAY BE NEGATED"
-.IX Header "SWITCHES WHICH MAY BE NEGATED"
-The following list shows all short parameter names which allow a prefix
-\&'n' to produce the negated form:
-.PP
-.Vb 6
-\& 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 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
-.Ve
-.PP
-Equivalently, the prefix 'no' or 'no\-' on the corresponding long names may be
-used.
-.SH "LIMITATIONS"
-.IX Header "LIMITATIONS"
-.IP "Parsing Limitations" 4
-.IX Item "Parsing Limitations"
-Perltidy should work properly on most perl scripts. It does a lot of
-self-checking, but still, it is possible that an error could be
-introduced and go undetected. Therefore, it is essential to make
-careful backups and to test reformatted scripts.
-.Sp
-The main current limitation is that perltidy does not scan modules
-included with 'use' statements. This makes it necessary to guess the
-context of any bare words introduced by such modules. Perltidy has good
-guessing algorithms, but they are not infallible. When it must guess,
-it leaves a message in the log file.
-.Sp
-If you encounter a bug, please report it.
-.IP "What perltidy does not parse and format" 4
-.IX Item "What perltidy does not parse and format"
-Perltidy indents but does not reformat comments and \f(CW\*(C`qw\*(C'\fR quotes.
-Perltidy does not in any way modify the contents of here documents or
-quoted text, even if they contain source code. (You could, however,
-reformat them separately). Perltidy does not format 'format' sections
-in any way. And, of course, it does not modify pod documents.
-.SH "FILES"
-.IX Header "FILES"
-.IP "Temporary files" 4
-.IX Item "Temporary files"
-Under the \-html option with the default \-\-pod2html flag, a temporary file is
-required to pass text to Pod::Html. Unix systems will try to use the \s-1POSIX\s0
-\&\fItmpnam()\fR function. Otherwise the file \fIperltidy.TMP\fR will be temporarily
-created in the current working directory.
-.IP "Special files when standard input is used" 4
-.IX Item "Special files when standard input is used"
-When standard input is used, the log file, if saved, is \fIperltidy.LOG\fR,
-and any errors are written to \fIperltidy.ERR\fR unless the \fB\-se\fR flag is
-set. These are saved in the current working directory.
-.IP "Files overwritten" 4
-.IX Item "Files overwritten"
-The following file extensions are used by perltidy, and files with these
-extensions may be overwritten or deleted: \fI.ERR\fR, \fI.LOG\fR, \fI.TEE\fR,
-and/or \fI.tdy\fR, \fI.html\fR, and \fI.bak\fR, depending on the run type and
-settings.
-.IP "Files extensions limitations" 4
-.IX Item "Files extensions limitations"
-Perltidy does not operate on files for which the run could produce a file with
-a duplicated file extension. These extensions include \fI.LOG\fR, \fI.ERR\fR,
-\&\fI.TEE\fR, and perhaps \fI.tdy\fR and \fI.bak\fR, depending on the run type. The
-purpose of this rule is to prevent generating confusing filenames such as
-\&\fIsomefile.tdy.tdy.tdy\fR.
-.SH "SEE ALSO"
-.IX Header "SEE ALSO"
-\&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3)
-.SH "VERSION"
-.IX Header "VERSION"
-This man page documents perltidy version 20180220.
-.SH "BUG REPORTS"
-.IX Header "BUG REPORTS"
-A list of current bugs and issues can be found at the \s-1CPAN\s0 site
-.PP
-.Vb 1
-\& https://rt.cpan.org/Public/Dist/Display.html?Name=Perl\-Tidy
-.Ve
-.PP
-To report a new bug or problem, use the link on this page.
-.SH "COPYRIGHT"
-.IX Header "COPYRIGHT"
-Copyright (c) 2000\-2018 by Steve Hancock
-.SH "LICENSE"
-.IX Header "LICENSE"
-This package is free software; you can redistribute it and/or modify it
-under the terms of the \*(L"\s-1GNU\s0 General Public License\*(R".
-.PP
-Please refer to the file \*(L"\s-1COPYING\*(R"\s0 for details.
-.SH "DISCLAIMER"
-.IX Header "DISCLAIMER"
-This package is distributed in the hope that it will be useful,
-but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
-\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0
-.PP
-See the \*(L"\s-1GNU\s0 General Public License\*(R" for more details.
projects / perltidy.git / blobdiff