This docco explains how to update perl.apache.org

The site is being anonymously checked out and built under
/home/perlwww/apache.org/modperl-docs and then synced into
/www/perl.apache.org. user 'perlwww' is in the 'perl' group, so
whatever it creates you should be able to modify at will. All the
files under /home/perlwww are made g+rwx to group 'perl', so you can
mess with files without becoming 'perlwww'.

*** sudo'ing to perlwww ***

Sometimes you need to sudo into the 'perlwww' user, to perform things
that only that user can do (e.g. modifying crontabs).

To sudo into the 'perlwww' user (assuming that you have the perms to
do so):

sudo -H -u perlwww bash

or:

sudo -H -u perlwww tcsh

*** Automatic Updates ***

The site is being updated automatically from the crontab. So all you
have to do is to commit your changes and wait for them to be picked up
by the update system.

This is the current crontab:

# every monday rebuild all, including pdf
30 05  * * 1 /home/perlwww/apache.org/modperl-docs/bin/site_build_force_pdf_index
# update all (only changes/no pdf) every 6 hours
15 6,12,18 * * * /home/perlwww/apache.org/modperl-docs/bin/site_build_index
# update all (only changes and pdfs) once a day
15 0 * * * /home/perlwww/apache.org/modperl-docs/bin/site_build_pdf_index

In order to modify the crontab you must sudo into the 'perlwww'
user. Notice that the crontab that everybody in the 'perl' group can
modify is the main reason for creating this special user.

If the updating script emits any warnings/errors, they will be sent to
the email address listed in /home/perlwww/.forward. (which is
currently my address by in the future I plan to change it to the
docs-dev list's address, so if I'm not around others will be able to
know that there is a problem and resolve it.)

*** Manual Updates ***

If for some reason you cannot wait before the automatic update
(e.g. if you've changed the template and don't want to wait a week for
the update to be picked up) there a few symlinks that you can use to
update the site:

/home/perlwww/apache.org/modperl-docs/bin/site_build                      
/home/perlwww/apache.org/modperl-docs/bin/site_build_index
/home/perlwww/apache.org/modperl-docs/bin/site_build_force                
/home/perlwww/apache.org/modperl-docs/bin/site_build_pdf
/home/perlwww/apache.org/modperl-docs/bin/site_build_force_index          
/home/perlwww/apache.org/modperl-docs/bin/site_build_pdf_index
/home/perlwww/apache.org/modperl-docs/bin/site_build_force_pdf_index

if the name includes:
force - the whole site is rebuilt
pdf   - builds pdfs
index - builds the index

the more you ask to do, the longer it will take the update. e.g.,
site_build only updates the html files, if you use site_build_index
the search index will be updated as well, site_build_pdf will update
htmls and pdfs, etc. site_build_force_pdf_index does a complete
rebuild of htmls, pdfs and the search index.

In most cases, when you do a minor update you just need to run:

  /home/perlwww/apache.org/modperl-docs/bin/site_build

so it'll rebuild the html of the modified files.

*** Full filesystem ***

When the /www/ fs is full and we attempt to copy files over it, the
whole online version may get rendered broken, since some (all) files
will be simply truncated to 0. so the script takes care of checking
whether the filesystem is under 95% (which happens quite often) and
won't update the online version if that's the case.

*** Resolving Problems ***

If the problem is with the build system email the docs-dev list. If
the problem with the apache.org machine email root@apache.org.