Description for a new framework

Hi,

OK, I finally wrote a sort of description for a new site's framework.
Hopefully it'll answer some questions raised about it. If something is
unclear, ask away.

I also played a bit with the templates (bigger logo, bigger font, etc.),
will post the results to the beta website soon for the review.

Directory and file layout

The portal directory of pgweb module consists of the following:
admin/ here the scripts to edit / translate the dynamic content reside.
The contents of this directory will obviously be installed on the
master server only.
cache/ not used.
intl/ contains the compiled (.mo) translations for gettext [1] l10n of
website. This should probably be removed from CVS, script to build
these files should be added instead (TODO).
layout/ contains images and stylesheets.
po/ contains human-readable gettext files.
system/ contains all the PHP code (more on this below)
template/ contains templates for the site's pages (more below)
tools/ contains helper tools. In particular, update.sql is the script
that updates the current database schema to the one used by the new
website. mirror.php is the script used for static mirror generation.

The PHP scripts rely on several PEAR [2] packages (TODO: create a
custom PEAR package with patched PEAR.php).

How the site is dispatched

The site uses mod_rewrite to redirect most of the requests to
handler.php script. The only exceptions are RSS feeds (dispatched via
rss.php) and form processing logic (the forms must obviously be
processed on the master site, handleform.php is used for this).

The pages' URLs for specific languages have the form
/path/to/page.html.lang, so that static mirrors may use Apache's
content negotiation [3], see also Debian [4] site as an example. For
the same reason links on the site should contain /path/to/page only,
if a directory listing is presumed (e.g. about/) then the trailing
slash is mandatory.

"Dynamic" vs. "static" templates, l10n

The site uses HTML_Template_Sigma template engine for HTML generation.
Template syntax is described in the manual available on the PEAR
website [5].

We consider the template "dynamic" if it has placeholders to be filled
with data received from the database and "static" in the other case.
There is only one copy of "dynamic" template for all the languages but
a copy of "static" template for each available language.

Thus "static" templates are translated as a whole, while "dynamic"
ones have English text wrapped in func_lang() calls, these are translated
to gettext() calls by the template engine.

"Dynamic" templates are located directly in the template/ directory,
"static" ones in template/{lang} directories, the layout of directories
within template/{lang} mimic the URLs on site.

Adding a new static page to the site does not require writing any PHP
code. One only adds a new HTML file to template/en (and optionally its
translations). Translations of dynamic content (news, events, etc.) are
done via admin/ scripts.

Preparing and adding a new translation

There are two tasks in translating the site to a new language:
1) Preparing gettext translation for dynamic templates and PHP scripts.
2) Translating the static pages.

Finally, one has to edit system/global/languages.php and add a new
language entry to the array[s] within. After the language is made known
to the website, there is a new task:

3) Translating the content stored in database (done via admin/ scripts).

Creating static mirrors

Unlike the previous mirroring script, mirror.php is just a generic HTTP
spider, it has very little code specific for postgresql.org. This
essentially means two things:
[+] You don't have to do anything special to add a new page. If a link
to the page does exist, it will be followed and the page will
be mirrored.
[-] Creating a static mirror may take quite a bit of time.

TODO: add command line arguments processing for mirror.php to be able to
limit it to a subset of pages without the need to edit the file.

[1] http://www.gnu.org/software/gettext/gettext.html
[2] http://pear.php.net/
[3] http://httpd.apache.org/docs/content-negotiation.html
[4] http://www.debian.org/
[5]
http://pear.php.net/manual/en/package.html.html-template-sigma.intro-syntax.php