Welcome to Perltidy!
    Perltidy is a tool to indent and reformat perl scripts.

    Perltidy is free software released under the GNU General Public License
    -- please see the included file "COPYING" for details.

    There are two source distribution files, a .tgz "tarball" for unix
    systems and a zip file, .zip for Windows. The only differences is that
    the line endings have been changed to <cr><lf> for the Windows version.

    Besides the source distribution files, a set of test files is available
    in a separate package (but there is no automated test procedure yet).
    These are distributed separately because they will not be of interest to
    the average user. If you do want the test files, you should untar or
    unzip them at the same directory that you untar or unzip the source
    files.

    Please see the ChangeLog file for notices of any recent updates.

    Please see the BUGS file for a list of all known open bugs.

  Installation - Unix

    Try this quick test. Look at lextest.pl with your editor - it's a mess.

    Now issue the command

     perl ./perltidy lextest.pl

    and then look at the output file, which will be lextest.pl.tdy. You
    should see a nicely formatted version of the program, in which Perltidy
    has added indentation, whitespace, and line breaks. This simple example
    illustrates what Perltidy does.

    Perltidy does not require any special modules. We just have to get the
    script in your path and, optionally, install two man pages. You probably
    know the routine:

    1. If the script is not executable, use

     chmod +x perltidy

    2. Verify that the initial line in Perltidy works for your system by
    entering:

     ./perltidy -h

    which should produce the usage text and then exit. This should usually
    work, but if it does not, you will need to change the first line in
    Perltidy to reflect the location of perl on your system. On a Unix
    system, you might find the path to perl with the command 'which perl'.

    3. Edit Makefile to have the correct paths. See the comments in the
    Makefile.

    You will need to become root unless you change the paths to point to
    somewhere in your home directory. Then issue the command

     make install

    This installs Perltidy and the man pages perltidy.1 and perl2web.1.

    5. Test the installation using

     perltidy -h

    You should see the usage screen. Then, if you installed the man pages,
    try

     man perltidy

    which should bring up the manual page.

    If you ever want to remove Perltidy, you can remove Perltidy and its man
    pages by hand or use

     make uninstall

  Windows ME Caution

    Perltidy should run under all versions of Windows. I test it on a
    Windows 95 system using Perl version 5.005_03 before each release, and I
    occasionally test it on a Windows 2000 system. I have seen one Windows
    ME system with Active State Perl that froze when attempting to run
    Perltidy, but I have other reports of success with Windows ME. In any
    case, if you install Perltidy on a Windows ME system, please close all
    applications before the first test to avoid loss of data in case the
    system freezes. If the first test works, it should be fine.

  Installation - Windows

    Here is how to install Perltidy under Windows. After unpacking the zip
    file, test the script:

     perl perltidy lextest.pl

    This will produce an output file lextest.pl.tdy which can be compared to
    the input file.

    Placing perltidy and perltidy.bat in your path should work. (You can
    determine your path by issuing the msdos command "PATH"). However, the
    batch file probably will not support file redirection. So, for example,
    to pipe the long help message through 'more', you might have to invoke
    Perltidy with perl directly, like this:

     perl \somepath\perltidy -h | more

    The documentation that comes with your perl distribution discusses other
    installation options.

  Windows 95/98 problem with syntax check

    There is a minor problem that you should be aware of if you are running
    perltidy (and perl) under Windows 95/98. The problem is that command.com
    always sends the standard error output to the screen. This makes it
    impossible for Perltidy to capture the message 'syntax OK' when it runs
    'perl -c' with the following code:

            my $perl_output = <<`END`;
                    perl -c $filename 2>&1
            END

    It also creates an empty file named &1. This means that you will have to
    check for syntax errors yourself. If you do not want to create the empty
    file &1, you can turn off syntax checking with the flag -nsyn. You can
    then check the syntax of a file manually by issuing the command

     perl -c filename

    There does not seem to be a good way around this problem.

    Windows 2000 does not have this problem.

  VMS Notes

    Perltidy runs under VMS, thanks to Michael Cartmell. You will probably
    want to use the .zip distribution file to get the <cr><lf> line endings.
    File extensions will use an underscore character instead of a dot, so

          perltidy myfile.pl

    will generate the output file myfile.pl_tdy instead of myfile.pl.tdy,
    and so on.

    If your script starts with a non-perl invocation, eg the following,

     $ perl                               !This is DCL not perl
     $ deck/dollar="$$Not-In-Perl$$"      !This is DCL not perl
     #!/usr/bin/perl

    you must use the -x flag to tell Perltidy to wait until the "hash bang"
    line to start parsing, like this:

          perltidy -x myfile.pl

    Information on running perl under VMS can be found at:

     http://w4.lns.cornell.edu/~pvhp/perl/VMS.html

WHAT NEXT
    The documentation has been supplied as man pages, as html files, and as
    text files.

    These documents can also be found at http://perltidy.sourceforge.net

    Reading the brief tutorial should help you use Perltidy effectively.

    Perltidy is still being developed, so please check sourceforge
    occasionally for updates if you find that it is useful. New releases are
    announced on freshmeat.net.

FEEDBACK / BUG REPORTS
    If you see ways to improve this document for the particular system on
    which you install Perltidy, please let the me know so that it can be
    updated.

    Bug reports, comments and suggestions are welcome. Attach the smallest
    piece of code which demonstrates the bug or issue, plus a .LOG file from
    a Perltidy run, if appropriate. Your efforts are greatly appreciated!

    Thank You

     Steve Hancock
     perltidy at users.sourceforge.net
     http://perltidy.sourceforge.net

