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.

Download

The mod_perl documentation lives in the svn.apache.org 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 modperl-docs directory in:

  % svn co http://svn.apache.org/repos/asf/perl/modperl/docs/trunk modperl-docs

You will now find a directory called modperl-docs in the current working directory which contains all the sources needed to build the site. See the Subversion Howto for more information.

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.

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 html2ps, 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 ps2pdf, which is included with the Ghostscript distribution: see http://www.ghostscript.com/ .

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 modperl-docs directory.

  % bin/build

This will place the site in the sub-directory dst_html. You may open index.html in there to start browsing the site.

If you are using the Windows operating system, please see the file INSTALL.win32 for some win32-specific information.

PDF version

Now, you can go back to your modperl-docs 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 dst_html too, with links on the HTML pages to the PDF versions. A dst_ps directory is also created, which contains intermediate HTML, PostScript and PDF files.

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 docs-cvs mailing list 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 config.cfg 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.

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:

• If the change is big, send the whole source file to the maintainer or the documentation mailing list.

• If you only add a paragraph/modify a line, please make sure you have the latest Subversion version, and then issue:

    % cd modperl-docs
    % svn diff > patch

  And send the patch file to the maintainer or the documentation mailing list, preferably inlined in your e-mail (so it's easier to review and follow if needed).

  For example if you have improved the src/docs/2.0/api/Apache/RequestUtil.pod 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.

When writing documentation, please make sure to read the files contained in admin/ in the SVN tree, especially style.pod, to see what guidelines you should follow.

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 swish-e binary, which you need to install if you don't have it already (you need swish-e 2.1 or higher).

Here is the httpd.conf configuration section:

  Alias /modperl/ "/usr/local/modperl-docs/dst_html/"
  <Directory "/usr/local/modperl-docs/dst_html">
      AllowOverride None
      Order allow,deny
      Allow from all
  </Directory>
  <Directory "/usr/local/modperl-docs/dst_html/search">
      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
  </Directory>

Here is the cron script that updates the site (save it as /usr/local/modperl-docs/bin/site_build):

  #!/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

Maintainers

Maintainer is the person(s) you should contact with updates, corrections and patches.

• the documentation mailing list

Authors

• Per Einar Ellefsen <per.einar (at) skynet.be>

Only the major authors are listed above. For contributors see the Changes file.