--- /dev/null
+<h1>PERLTIDY INSTALLATION NOTES</h1>
+
+<h1>Get a distribution file</h1>
+
+<ul>
+<li><p>Source Files in .tar.gz and .zip format</p>
+
+<p>This document tells how to install perltidy from the basic source
+distribution files in <code>.tar.gz</code> or <code>.zip</code> format. These files are
+identical except for the line endings. The <code>.tar.gz</code> has Unix style
+line endings, and the <code>.zip</code> file has Windows style line endings. The
+standard perl MakeMaker method should work for these in most cases. </p></li>
+<li><p>Source files in RPM and .deb format</p>
+
+<p>The web site also has links to RPM and Debian .deb Linux packages, which may be
+convenient for some users.</p></li>
+</ul>
+
+<h1>Quick Test Drive</h1>
+
+<p>If you want to do a quick test of perltidy without doing any installation, get
+a <code>.tar.gz</code> or a <code>.zip</code> source file and see the section below "Method 2: Installation
+as a single binary script".</p>
+
+<h1>Uninstall older versions</h1>
+
+<p>In certain circumstances, it is best to remove an older version
+of perltidy before installing the latest version. These are:</p>
+
+<ul>
+<li><p>Uninstall a Version older than 20020225</p>
+
+<p>You can use perltidy -v to determine the version number. The first
+version of perltidy to use Makefile.PL for installation was 20020225, so
+if your previous installation is older than this, it is best to remove
+it, because the installation path may now be different. There were up
+to 3 files these older installations: the script <code>perltidy</code> and
+possibly two man pages, <code>perltidy.1</code> and <code>perl2web.1</code>. If you saved
+your Makefile, you can probably use <code>make uninstall</code>. Otherwise, you
+can use a <code>locate</code> or <code>find</code> command to find and remove these files.</p></li>
+<li><p>Uninstall older versions when changing installation method</p>
+
+<p>If you switch from one installation method to another, the paths to the
+components of perltidy may change, so it is probably best to remove the older
+version before installing the new version. If your older installation method
+had an uninstall option (such as with RPM's and debian packages), use it.
+Otherwise, you can locate and remove the older files by hand. There are two
+key files: <code>Tidy.pm</code> and <code>perltidy</code>. In addition, there may be one or two
+man pages, something like <code>Perl::Tidy.3pm</code> and <code>perltidy.1p</code>. You can use a
+<code>locate</code> and/or <code>find</code> command to find and remove these files. After
+installation, you can verify that the new version of perltidy is working with
+the <code>perltidy -v</code> command.</p></li>
+</ul>
+
+<h1>Two Installation Methods - Overview</h1>
+
+<p>These are generic instructions. Some system-specific notes and hints
+are given in later sections. </p>
+
+<p>Two separate installation methods are possible. </p>
+
+<ul>
+<li><p>Method 1: Standard Installation Method</p>
+
+<p>The standard method based on MakeMaker should work in a normal perl
+environment. This is the recommended installation procedure for
+systems which support it.</p>
+
+<pre><code> perl Makefile.PL
+ make
+ make test
+ make install
+</code></pre>
+
+<p>The <code>make</code> command is probably <code>nmake</code> under a Windows system. You
+may need to become root (or administrator) before doing the <code>make
+install</code> step. </p></li>
+<li><p>Method 2: Installation as a single binary script</p>
+
+<p>If you just want to take perltidy for a quick test drive without installing it,
+or are having trouble installing modules, you can bundle it all in one
+independent executable script. This might also be helpful on a system for
+which the Makefile.PL method does not work, or if you are temporarily a guest
+on some system, or if you want to try hacking a special version of perltidy
+without messing up your regular version. </p>
+
+<p>You just need to uncompress the source distribution, cd down into it, and enter
+the command:</p>
+
+<pre><code> perl pm2pl
+</code></pre>
+
+<p>which will combine the pieces of perltidy into a single script named
+<code>perltidy</code> in the current directory. This script should be
+fully functional. Try it out on a handy perl script, for example</p>
+
+<pre><code>perl perltidy Makefile.PL
+</code></pre>
+
+<p>This should create <code>Makefile.PL.tdy</code>.</p></li>
+<li><p>After Installation</p>
+
+<p>After installation by either method, verify that the installation worked
+and that the correct new version is being by entering:</p>
+
+<pre><code>perltidy -v
+</code></pre>
+
+<p>If the version number disagrees with the version number embedded in the
+distribution file name, search for and remove the old version.
+For example, under a Unix system, the command <code>which perltidy</code> might
+show where it is. Also, see the above notes on uninstalling older
+versions.</p>
+
+<p>On a Unix system running the <code>bash</code> shell, if you had a previous
+installation of perltidy, you may have to use </p>
+
+<pre><code>hash -r
+</code></pre>
+
+<p>to get the shell to find the new one.</p>
+
+<p>After <code>perltidy</code> is installed, you can find where it will look for
+configuration files and environment variables on your system with
+the command:</p>
+
+<pre><code>perltidy -dpro
+</code></pre></li>
+<li><p>How to Uninstall</p>
+
+<p>Unfortunately, the standard Perl installation method does not seem able
+to do an uninstall.</p>
+
+<p>But try this:</p>
+
+<pre><code>make uninstall
+</code></pre>
+
+<p>On some systems, it will give you a list of files to remove by hand. If
+not, you need to find the script <code>perltidy</code> and its module file
+<code>Tidy.pm</code>, which will be in a subdirectory named <code>Perl</code> in the site
+library.</p>
+
+<p>If you installed perltidy with the alternative method, you should just
+reverse the steps that you used.</p></li>
+</ul>
+
+<h2>Unix Installation Notes</h2>
+
+<ul>
+<li><p>Alternative method - Unix</p>
+
+<p>If the alternative method is used, test the script produced by the
+<code>pm2pl</code> perl script:</p>
+
+<pre><code>perl ./perltidy somefile.pl
+</code></pre>
+
+<p>where <code>somefile.pl</code> is any convenient test file, such as <code>Makefile.PL</code>
+itself. Then,</p>
+
+<p>1. If the script is not executable, use </p>
+
+<pre><code>chmod +x perltidy
+</code></pre>
+
+<p>2. Verify that the initial line in perltidy works for your system by
+entering:</p>
+
+<pre><code>./perltidy -h
+</code></pre>
+
+<p>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
+<code>perltidy</code> 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'.</p>
+
+<p>3. A sample <code>Makefile</code> for this installation method is <code>Makefile.npm</code>.
+Edit it to have the correct paths.</p>
+
+<p>You will need to become root unless you change the paths to point to
+somewhere in your home directory. Then issue the command</p>
+
+<pre><code>make -f Makefile.npm install
+</code></pre>
+
+<p>This installs perltidy and the man page perltidy.1. </p>
+
+<p>5. Test the installation using</p>
+
+<pre><code>perltidy -h
+</code></pre>
+
+<p>You should see the usage screen. Then, if you installed the man pages,
+try</p>
+
+<pre><code>man perltidy
+</code></pre>
+
+<p>which should bring up the manual page. </p>
+
+<p>If you ever want to remove perltidy, you can remove perltidy and its man
+pages by hand or use</p>
+
+<pre><code>make uninstall
+</code></pre></li>
+</ul>
+
+<h2>Windows Installation Notes</h2>
+
+<p>On a Windows 9x/Me system you should CLOSE ANY OPEN APPLICATIONS to
+avoid losing unsaved data in case of trouble.</p>
+
+<ul>
+<li><p>Standard Method - Windows</p>
+
+<p>After you unzip the distribution file, the procedure is probably this:</p>
+
+<pre><code> perl Makefile.PL
+ nmake
+ nmake test
+ nmake install
+</code></pre>
+
+<p>You may need to download a copy of <code>unzip</code> to unzip the <code>.zip</code> distribution
+file; you can get this at
+http://www.info-zip.org/pub/infozip/UnZip.html</p>
+
+<p>If you have ActiveState
+Perl, the installation method is outlined at
+http://aspn.activestate.com//ASPN/Reference/Products/ActivePerl/faq/Windows/ActivePerl-Winfaq9.html#How_can_I_use_modules_from_CPAN_</p>
+
+<p>You may need to download a copy of Microsoft's <code>nmake</code> program from
+ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe</p>
+
+<p>If you are not familiar with installing modules, or have trouble doing
+so, and want to start testing perltidy quickly, you may want to use the
+alternative method instead (next section).</p></li>
+<li><p>Alternative Method - Windows</p>
+
+<p>From the main installation directory, just enter</p>
+
+<pre><code>perl pm2pl
+</code></pre>
+
+<p>Placing the resulting file <code>perltidy</code> and the example batch file
+<code>perltidy.bat</code>, located in the <code>examples</code> directory, in your path should
+work. (You can determine your path by issuing the msdos command
+<code>PATH</code>). 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:</p>
+
+<pre><code>perl \somepath\perltidy -h | more
+</code></pre>
+
+<p>The batch file will not work properly with wildcard filenames, but you may
+use wildcard filenames if you place them in quotes. For example</p>
+
+<pre><code>perltidy '*.pl'
+</code></pre></li>
+</ul>
+
+<h2>VMS Installation Notes</h2>
+
+<ul>
+<li><p>Links to VMS Utilities and Documentation</p>
+
+<p>To install perltidy you will need the following utilities Perl, of
+course, source with VMS goodies available from
+http://www.sidhe.org/vmsperl or binary available from the Compaq OpenVMS
+freeware CD. To unpack the source either gunzip and vmstar available
+from the Compaq OpenVMS freeware CD or zip available from
+http://www.info-zip.org/</p>
+
+<p>To build perltidy you can use either <strong>MMS</strong>, Compaq's VMS equivalent of
+make, or <strong>MMK</strong>, an <strong>MMS</strong> clone available from
+http://www.madgoat.com.</p>
+
+<p>Information on running perl under VMS can be found at:
+http://w4.lns.cornell.edu/~pvhp/perl/VMS.html</p></li>
+<li><p>Unpack the source:</p>
+
+<pre><code>$ unzip -a perl-tidy-yyyymmdd.zip ! or
+
+
+$ unzip /text=auto perl-tidy-yyyymmdd.zip ! or
+
+
+$ gunzip perl-tidy-yyyymmdd.tgz
+$ vmstar perl-tidy-yyyymmdd.tar
+</code></pre></li>
+<li><p>Build and install perltidy under VMS:</p>
+
+<pre><code>$ set default [.perl-tidy-yyymmdd]
+$ perl perltidy.pl
+$ mmk
+$ mmk test
+$ mmk install
+</code></pre></li>
+<li><p>Using Perltidy under VMS</p>
+
+<p>Create a symbol. This should be put in a logon script, eg sylogin.com</p>
+
+<pre><code>$ perltidy == "perl perl_root:[utils]perltidy."
+</code></pre>
+
+<p>Default parameters can be placed in a <code>perltidyrc</code> file. Perltidy
+looks for one in the following places and uses the first found if the
+logical <code>PERLTIDY</code> is a file and the file exists then that is used if the
+logical <code>PERLTIDY</code> is a directory then look for a <code>.perltidyrc</code> file in the
+directory look for a <code>.perltidyrc</code> file in the user's home directory</p>
+
+<p>To see where the search is done and which <code>.perltidyrc</code> is used type</p>
+
+<pre><code>$ perltidy -dpro
+</code></pre>
+
+<p>A system <code>PERLTIDY</code> logical can be defined pointing to a file with a
+minimal configuration, and users can defined their own logical to use a
+personal <code>.perltidyrc</code> file.</p>
+
+<pre><code>$ define /system perltidy perl_root:[utils]perltidy.rc
+</code></pre></li>
+<li><p>The -x Parameter</p>
+
+<p>If you have one of the magic incantations at the start of perl scripts,
+so that they can be invoked as a .com file, then you will need to use
+the <strong>-x</strong> parameter which causes perltidy to skip all lines until it
+finds a hash bang line eg <code>#!perl -w</code>. Since it is such a common
+option this is probably a good thing to put in a <code>.perltidyrc</code> file.</p></li>
+<li><p>VMS File Extensions</p>
+
+<p>VMS file extensions will use an underscore character instead of a dot,
+when necessary, to create a valid filename. So </p>
+
+<pre><code> perltidy myfile.pl
+</code></pre>
+
+<p>will generate the output file <code>myfile.pl_tdy</code> instead of
+<code>myfile.pl.tdy</code>, and so on. </p></li>
+</ul>
+
+<h1>Troubleshooting / Other Operating Systems</h1>
+
+<p>If there seems to be a problem locating a configuration file, you can see
+what is going on in the config file search with:</p>
+
+<pre><code>perltidy -dpro
+</code></pre>
+
+<p>If you want to customize where perltidy looks for configuration files,
+look at the routine 'find_config_file' in module 'Tidy.pm'. You should
+be able to at least use the '-pro=filename' method under most systems. </p>
+
+<p>Remember to place quotes (either single or double) around input
+parameters which contain spaces, such as file names. For example:</p>
+
+<pre><code>perltidy "file name with spaces"
+</code></pre>
+
+<p>Without the quotes, perltidy would look for four files: <code>file</code>,
+<code>name</code>, <code>with</code>, and <code>spaces</code>.</p>
+
+<p>If you develop a system-dependent patch that might be of general
+interest, please let us know.</p>
+
+<h1>CONFIGURATION FILE</h1>
+
+<p>You do not need a configuration file, but you may eventually want to
+create one to save typing; the tutorial and man page discuss this.</p>
+
+<h1>SYSTEM TEMPORARY FILES</h1>
+
+<p>Perltidy needs to create a system temporary file when it invokes
+Pod::Html to format pod text under the -html option. For Unix systems,
+this will normally be a file in /tmp, and for other systems, it will be
+a file in the current working directory named <code>perltidy.TMP</code>. This file
+will be removed when the run finishes.</p>
+
+<h1>DOCUMENTATION</h1>
+
+<p>Documentation is contained in <strong>.pod</strong> format, either in the <code>docs</code> directory
+or appended to the scripts. </p>
+
+<p>These documents can also be found at http://perltidy.sourceforge.net</p>
+
+<p>Reading the brief tutorial should help you use perltidy effectively. <br />
+The tutorial can be read interactively with <strong>perldoc</strong>, for
+example</p>
+
+<pre><code>cd docs
+perldoc tutorial.pod
+</code></pre>
+
+<p>or else an <code>html</code> version can be made with <strong>pod2html</strong>:</p>
+
+<pre><code>pod2html tutorial.pod >tutorial.html
+</code></pre>
+
+<p>If you use the Makefile.PL installation method on a Unix system, the
+<strong>perltidy</strong> and <strong>Perl::Tidy</strong> man pages should automatically be installed.
+Otherwise, you can extract the man pages with the <strong>pod2xxxx</strong> utilities, as
+follows:</p>
+
+<pre><code>cd bin
+pod2text perltidy >perltidy.txt
+pod2html perltidy >perltidy.html
+
+cd lib/Perl
+pod2text Tidy.pm >Tidy.txt
+pod2html Tidy.pm >Tidy.html
+</code></pre>
+
+<p>After installation, the installation directory of files may be deleted. </p>
+
+<p>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.</p>
+
+<h1>CREDITS</h1>
+
+<p>Thanks to the many programmers who have documented problems, made suggestions and sent patches. </p>
+
+<h1>FEEDBACK / BUG REPORTS</h1>
+
+<p>If you see ways to improve these notes, please let us know.</p>
+
+<p>A list of current bugs and issues can be found at the CPAN site <a href="https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy">https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy</a></p>
+
+<p>To report a new bug or problem, use the link on this page . </p>
projects / perltidy.git / blobdiff