--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
+.\"
+.\" 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" ''
+'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.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" 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 "2012-06-29" "perl v5.10.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\s0\*(R" 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\s0
+\&\s-1OPTIONS\s0\*(R".
+.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\s0 \s-1OPTIONS\s0\*(R".
+.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 \-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 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
+if the \fB\-html\fR flag is set.
+.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\-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\-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 "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.
+.RE
+.RS 4
+.RE
+.IP "\fB\-syn\fR, \fB\-\-check\-syntax\fR" 4
+.IX Item "-syn, --check-syntax"
+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\-io\fR, \fB\-\-indent\-only\fR" 4
+.IX Item "-io, --indent-only"
+This flag is used to deactivate all formatting and line break changes
+within non-blank lines of code.
+When it is in effect, the only change to the script will be
+to the indentation and blank lines.
+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.
+.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.
+.Sp
+This flag has no effect when perltidy is used to generate html.
+.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 compatability.
+.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 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
+.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.
+.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, is not do do this.
+.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\-string\fR" 4
+.IX Item "-cscl=string, or --closing-side-comment-list-string"
+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 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.
+=item \fB\-cscb\fR, or \fB\-\-closing\-side\-comments\-balanced\fR
+.Sp
+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 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 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\-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 a synonym 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 "Vertical tightness 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 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
+the exception of one-line blocks, they will normally remain on a
+separate line.
+.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 3
+\& \-sop or \-\-stack\-opening\-paren
+\& \-sohb or \-\-stack\-opening\-hash\-brace
+\& \-sosb or \-\-stack\-opening\-square\-bracket
+.Ve
+.Sp
+The flag \fB\-sot\fR is a synonym for \fB\-sop \-sohb \-sosb\fR.
+.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 3
+\& \-scp or \-\-stack\-closing\-paren
+\& \-schb or \-\-stack\-closing\-hash\-brace
+\& \-scsb or \-\-stack\-closing\-square\-bracket
+.Ve
+.Sp
+The flag \fB\-sct\fR is a synonym for \fB\-scp \-schb \-scsb\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, '=>', requires 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 6
+\& n=0 break at all commas after =>
+\& n=1 stable: break at all commas after => unless this would break
+\& an existing one\-line container (default)
+\& n=2 break at all commas after =>, but try to form the maximum
+\& maximum one\-line container lengths
+\& n=3 do not treat commas after => specially at all
+.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 would
+be needed.
+.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 exceeed.
+.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 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 <\-blbp=1>.
+.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 compatability 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\-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 compatability 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 compatability 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
+Note that the \-st and \-se flags make perltidy act as a filter on one file only.
+These can be overridden with \-nst and \-nse if necessary.
+.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 possbile 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\s0 / 2000 / \s-1XP\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 configuation 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 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\-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\-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\s0\*(R". 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\s0 3.2 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.
+.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.
+.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 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 20120701.
+.SH "CREDITS"
+.IX Header "CREDITS"
+Michael Cartmell supplied code for adaptation to \s-1VMS\s0 and helped with
+v\-strings.
+.PP
+Yves Orton supplied code for adaptation to the various versions
+of Windows.
+.PP
+Axel Rose supplied a patch for MacPerl.
+.PP
+Hugh S. Myers designed and implemented the initial Perl::Tidy module interface.
+.PP
+Many others have supplied key ideas, suggestions, and bug reports;
+see the \s-1CHANGES\s0 file.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+.Vb 3
+\& Steve Hancock
+\& email: perltidy at users.sourceforge.net
+\& http://perltidy.sourceforge.net
+.Ve
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 2000\-2010 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\s0\*(R" for details.
+.SH "DISCLAIMER"
+.IX Header "DISCLAIMER"
+This package is distributed in the hope that it will be useful,
+but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
+\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.
+.PP
+See the \*(L"\s-1GNU\s0 General Public License\*(R" for more details.