=head1 NAME Documentation =head1 Description You may want to download and install the mod_perl documentation locally for easier reading, or to submit documentation patches. To install the documentation you will have to install the whole site at the same time though, but this should just be a benefit because you can mirror the whole site locally and have access to all the information available here. =head1 Download The mod_perl documentation lives in the C Subversion server. To get it, you will need to checkout a copy. Assuming you have Subversion installed, run the following command from the directory you want to place the I directory in: % svn co http://svn.apache.org/repos/asf/perl/modperl/docs/trunk modperl-docs You will now find a directory called I in the current working directory which contains all the sources needed to build the site. See the L for more information. =head1 Build The build process is very simple, as we have developed a number of tools which are very helpful in this task. However, you will need a number of prerequisites before starting. =head2 Prerequisites DocSet: while it is included with the Subversion distribution, please download it from CPAN and install the latest version. It will install the tool C, which is needed to build the PDF version, and also a number of Perl modules (it will tell you the Perl modules prerequisites). For the PDF version, you will also need a command-line tool called C, which is included with the Ghostscript distribution: see http://www.ghostscript.com/ . =head2 Normal build process The programs used to build the site are included in the directory you checked out from SVN. To build the whole site, run this while being placed in the I directory. % bin/build This will place the site in the sub-directory I. You may open I in there to start browsing the site. If you are using the Windows operating system, please see the file I for some win32-specific information. =head2 PDF version Now, you can go back to your I directory. Building the PDF version is as easy as with the HTML version, just do a simple: % bin/build -d And the PDF version will be built. This is often very time-consuming and heave on resources though. The results will be placed in I too, with links on the HTML pages to the PDF versions. A I directory is also created, which contains intermediate HTML, PostScript and PDF files. =head1 Keeping your local copy up to date Now that you have a working copy of the mod_perl site, you will want to keep your documentation up to date. It is updated quite frequently, so you might want to follow the L to see when changes are made. Once you see a change is made, you need to update your Subversion working copy, and re-build the site (although it will only rebuild modified files). % svn up % bin/build Rebuilding the PDF version is just as easy, just run: % bin/build -d There are some times however when a simple rebuild will not be enough: usually when there are changes made to the design or to I files. In that case, you will need to force the whole rebuild: % bin/build -f % bin/build -df # if you want PDF to be rebuilt. =head1 Submitting documentation patches We warmly welcome any updates to the documentation. To send us a documentation patch, please update your Subversion tree, and then, depending on the patch: =over =item * If the change is big, send the whole source file to the maintainer or the L. =item * If you only add a paragraph/modify a line, please make sure you have the I Subversion version, and then issue: % cd modperl-docs % svn diff > patch And send the I file to the maintainer or the L, preferably inlined in your e-mail (so it's easier to review and follow if needed). For example if you have improved the I doc, to generate the patch do: % cd modperl-docs % svn diff src/docs/2.0/api/Apache/RequestUtil.pod > patch This approach will get the diff of only that file. =back When writing documentation, please make sure to read the files contained in I in the SVN tree, especially I, to see what guidelines you should follow. =head1 Mirroring the Site If you want to mirror the site, it's the easiest to recreate the site from scratch on your mirror, rather than using the normal mirroring process. This is because the site is quite big and by simply copying it you won't get the search working. If you decided to build the site's mirror by yourself, here is the information about how to setup the server configuration and keep it in sync with the master site using the crontab jobs: Make sure to adjust the paths and other details in the following files before using them. That includes the URL of the site, the location of the source files and the location of the C binary, which you need to install if you don't have it already (you need swish-e 2.1 or higher). Here is the I configuration section: Alias /modperl/ "/usr/local/modperl-docs/dst_html/" AllowOverride None Order allow,deny Allow from all SetEnv SWISH_BINARY_PATH "/usr/local/bin/swish-e" SetEnv PERL5LIB "/usr/local/modperl-docs/dst_html/search/modules" Options +ExecCGI AddHandler cgi-script cgi Here is the cron script that updates the site (save it as I): #!/usr/bin/perl -w # file: site_build # # this script does different things depending on how it was named (or # a symlink) if the name includes: # force - the whole site is rebuilt # pdf - builds pdfs # index - builds the index # # the easiest way is to use symlinks to the same script # # by default it only updates the changed files use strict; my $src = "/usr/local/modperl-docs"; umask 0002; my $HOME = $ENV{HOME}; $ENV{PATH} = "/sbin:/bin:/usr/sbin:/usr/bin:/usr/games:/usr/local/bin:/usr/X11R6/bin:$HOME"; $ENV{PERL5LIB} = "$HOME/lib/perl5/5.00503:$HOME/lib/perl5/site_perl/5.005:$HOME/lib/perl5/site_perl:$HOME/lib/perl5"; $ENV{MODPERL_SITE} = 'http://theoryx5.uwinnipeg.ca/modperl'; $ENV{SWISH_BINARY_PATH} = '/usr/local/bin/swish-e'; chdir $src; # Do different things depending on our name my ($name) = $0 =~ m|([^/]+)$|; my $reindex = $name =~ /index/ ? 1 : 0; my $flags = ''; $flags .= 'f' if $name =~ /force/; $flags .= 'd' if $name =~ /pdf/; $flags = $flags ? "-$flags" : ""; system("svn up >/dev/null 2>&1"); system("bin/build $flags"); system("bin/makeindex") if $reindex; Next, create the symlinks: % ln -s /usr/local/modperl-docs/bin/site_build \ /usr/local/modperl-docs/bin/site_build_force_pdf_index % ln -s /usr/local/modperl-docs/bin/site_build \ /usr/local/modperl-docs/bin/site_build_index % ln -s /usr/local/modperl-docs/bin/site_build \ /usr/local/modperl-docs/bin/site_build_pdf_index And finally install the crontab: # every monday rebuild all, including pdf 30 03 * * 1 /usr/local/modperl-docs/bin/site_build_force_pdf_index # update all (only changes/no pdf) every 6 hours 15 6,12,18 * * * /usr/local/modperl-docs/bin/site_build_index # update all (only changes and pdfs) once a day 15 0 * * * /usr/local/modperl-docs/bin/site_build_pdf_index =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. =over =item * the L =back =head1 Authors =over =item * Per Einar Ellefsen Eper.einar (at) skynet.beE =back Only the major authors are listed above. For contributors see the Changes file. =cut