DocPerl::Install
POD |CODE
				
			


 1  =head1 DocPerl Installation
 2  
 3  DocPerl is straightforward to install.  It consists of wholely of Perl scripts
 4  in text files and is therefore quite transparent to anyone wishing to delve
 5  into the internals or to troubleshoot particular errors.  Installation on a
 6  standard Unix/Linux system is performed with no requirement to have more than
 7  basic Unix skills.
 8  
 9  DocPerl is designed to run on any platform that has Perl installed.
 10  
 11  =head1 Prerequisites
 12  
 13  DocPerl requires
 14  
 15  =over 4
 16  
 17  =item *
 18  
 19  Perl version 5.6 or greater
 20  
 21  =item *
 22  
 23  A webserver (eg. Apache, IIS, LightHTTPD etc...)
 24  
 25  =back
 26  
 27  Perl modules required that may not be already installed are:
 28  
 29  =over 4
 30  
 31  =item *
 32  
 33  Template Toolkit
 34  
 35  =item *
 36  
 37  Readonly
 38  
 39  =item *
 40  
 41  Config::Std
 42  
 43  =item *
 44  
 45  version
 46  
 47  =item *
 48  
 49  Pod::POM
 50  
 51  =back
 52  
 53  The installation of DocPerl checks if these modules have been installed. If
 54  any of these modules has not been installed you can install them via the
 55  following methods:
 56  
 57  Generic Unix/Linux
 58  
 59   $ perl -MCPAN -e 'install Template; install Readonly ...'
 60  
 61  or (on Debian based systems?)
 62  
 63    $ cpan Template Readonly ...
 64  
 65  Windows Active Perl
 66  
 67    $ ppm install Template
 68    $ ppm install Readonly
 69    ...
 70  
 71  If you have any problems try going to the help forums at
 72  L<https://sourceforge.net/forum/forum.php?forum_id=553595>
 73  
 74  =head1 Download
 75  
 76  To install DocPerl download the latest version from
 77  L<http://sourceforge.net/project/showfiles.php?group_id=163244>.
 78  
 79  The download is an archive file in the form F<docperl-vX.X.X.tar.gz>.
 80  Extract the archive to the directory that you wish DocPerl to run from.
 81  
 82  E.g.
 83  
 84   $ tar xvzf docperl-v1.0.0.tar.gz
 85  
 86  =head1 Installation
 87  
 88  From the DocPerl directory run C<./checksetup.pl>
 89  
 90  This performs a check that your installation of Perl has all the modules
 91  required to run DocPerl.  If you have all the required modules then you can
 92  proceed to the next step.  If you don't have all the required modules you
 93  will need to install them before you can proceed in your installation of
 94  DocPerl.  Please see the Prerequisites section for further information.
 95  
 96  C<./checksetup.pl> can also be used to create cached versions of POD files
 97  to speed usage and enable full text searching and function name searching.
 98  
 99  For for example use the command:
 100  
 101    $ ./checksetup.pl -c pod,text,function
 102  
 103  this will cache the POD and enable full text and function searching.
 104  
 105  For more details on the checksetup.pl program run:
 106  
 107    $ ./checksetup.pl --help
 108  
 109  See L<DocPerl::Config> for a detailed description of the F<docperl.conf>
 110  configuration files options.
 111  
 112  This is as much configuration as the DocPerl files require.  Now all that
 113  is needed to use your DocPerl installation is to configure your web server
 114  to see DocPerl.
 115  
 116  =head1 Web Server Configuration
 117  
 118  Included in this documentation is example Apache configuration.  For other
 119  web servers you will need to configure as appropriate.
 120  
 121  To configure DocPerl with Apache adding the following to your configuration
 122  file is all that is required:
 123  
 124   <Directory "/path/to/docperl">
 125       Options +ExecCGI
 126       AllowOverride Limit
 127       DirectoryIndex docperl.cgi
 128       AddHandler cgi-script .cgi
 129   </Directory>
 130  
 131  =head2 Security
 132  
 133  Some more work may be required to make DocPerl secure if you have some of the
 134  less safe configuration options turned on or if you don't want your internal
 135  modules to be publicly available. Also look at the F<.htaccess.example> (found
 136  in the DocPerl directory) for more security settings.
 137  
 138  =head1 Windows
 139  
 140  Installation on Windows has improved since the initial realeses. The
 141  dependencies on command line programs have been removed.
 142  
 143  The major problems you may now encounter are setting setting the Perl scripts
 144  bang line to you Perl location (if you do not download the windows zip file
 145  or your Perl is not installed into F<C:/Perl>). Work-arounds are to change the
 146  bang line from:
 147  
 148   #!/usr/bin/perl
 149  
 150  to
 151  
 152   #!"C:/perl/bin/perl.exe"
 153  
 154  or where ever your Perl is installed.
 155  
 156  You can set Apache to use file extensions instead (see your Apache
 157  documentation for details)
 158  
 159  * If you are using Active Perl's ppm to get the Template Toolkit modules
 160  you may encounter some difficulty, as ppm install Template does not appear to
 161  install the Template Toolkit. You will probably need to use CPAN.
 162  
 163  =head1 Upgrading
 164  
 165  If you are upgrading from DocPerl version 0.3 or earlier there have been some
 166  structural changes to DocPerl.
 167  
 168  Firstly the file docperl.conf has been moved from the data directory up one
 169  level to the base directory (to allow you to set where the data directory
 170  is stored).
 171  
 172  Also the templates have been renamed to have the extension .tmpl added to
 173  their names, so if you have customized any templates, you will need to add
 174  F<.tmpl> to their names.
 175  
 176  =cut