Subject: Todo for 'portal', programmers perspective

From: Alexey Borzov <[email-masked]>
Date: Thu, 15 Jan 2004 18:29:00 +0300

Greetings!

After having a bit of discussion here and after getting acquainted with 
the source code of the "next generation" postgresql.org in pgweb/portal 
I want to give some ideas of mostly architectural and political nature.

To prevent the questions like "who the f*ck is Alexey": I am a PHP 
programmer, a member of the PEAR[1] community, with several opensource 
packages released[2]. I also have experience programming the sites that 
are  more complex than postgresql.org. Unfortunately these are 
Russian-only, so no real use giving links here.

First of all, I'd like to thank Andreas Grabmüller for all the work he 
did on portal module. The code *is* working and that means we only have 
to tweak it a bit and not to write everything from scratch.

Now on to tweaking.

What is IMO really needed right now is removing the obstacles and 
bottlenecks of website development. Consider the following examples:
1) If all the static content (i.e. the content that does not change 
often) is stored in the database and is editable only through 
web-interface then there is a bottleneck: the person who gives access to 
web-interface. If the interface is not robust enough to let 
not-quite-trusted people use it, then the bottleneck is even more 
narrow. On the other hand, if the content is available in public CVS, 
then every one may check it out and edit it and later submit for inclusion.

2) If some of the critical data --- DB schema, docs, ToDo lists --- is 
missing from CVS then the person wishing to participate in the 
development will not be able to do this without fishing for the 
appropriate info somewhere.

3) If site's layout is kept in the spaghetti of PHP and HTML and even 
duplicated in several files then the person wishing to tweak the design 
or to contribute the completely new one will be unable to do this. The 
bottleneck is again the person with the knowledge of this spaghetti.

* I18n and l10n issues

There are separate internationalization tasks:
1) Translating the framework itself and static content

For the pages that are mostly the same in different languages and for 
the PHP scripts themselves gettext extension or something like this can 
be used. Current solution with {LNG_whatever} placeholders is extremely 
fragile, as all translations should be updated manually in several places.

Text-intensive pages with not much layout must be kept in CVS in all 
availbale languages.

The benefits of this approach: people wishing to translate website will 
be able to checkout the current code and work on the website without 
having to ask anyone.

2) Making it possible to publish dynamic content in several languages

This is mostly done, but not actually usable without robust admin interface.

For Dave, on documentation: PostgreSQL documentation is being done in 
DocBook[3] this is SGML (or XML) based format that does not have 
presentation markup, unlike HTML. It is converted into other formats via 
special stylesheets. This is how PostgreSQL's HTML and PDF docs are 
being generated. If there is a need to translate the docs, then DocBook 
source should be translated, and there are special tools for this. You 
can consult PHP documentation HowTo[4], it is a good introduction for 
beginners.

* Separation of HTML from the actual code.

This is quite simple: if someone wants to tweak the website's layout, he 
must be able to do this without having to bother with the actual code. 
Thus HTML-only templates (or with *minimal* PHP) are needed.

Very few templates will be actually needed: one for the whole website 
"frame" and one for each distinct page that is available now in "www" 
module, of these some will be language specific.

Now lets move to more technical issues

* Static page generation

This is working now, I suppose. I only want to suggest using 
pagename.lang.html instead of lang/pagename.html to be able to use 
Apache's content negotiation[5] on static website mirrors, as suggested 
by Peter Eisentraut.

* Administrative interface

There is fair amount of work needed here. There should be builtin 
authentication and access control system here, so that people having 
access to e.g. German translation couldn't f*ck up anything else.

I think to roll out a "new" website, the following should be done:
1) Separate HTML from the code.
2) Decide upon the translation infrastructure.
3) Move all the static pages from "www" into "portal" in the form of 
HTML-only templates.

That's all, the site can be published.

As soon as the people send in translations of static content we can add 
them to the site. As soon as a more robust admin interface is in place, 
people can be given rights to publish news, events and surveys in their 
languages.

As soon as someone can come up with a professional-looking design 
(sorry, Dave) the current one can be easily replaced.

[1] http://pear.php.net/
[2] http://pear.php.net/user/avb
[3] http://www.docbook.org/
[4] http://www.php.net/manual/howto/
[5] http://httpd.apache.org/docs/content-negotiation.html

---

From: Alexey Borzov <[email-masked]>
Date: Thu, 15 Jan 2004 19:56:47 +0300

Hi!

Andreas Grabmüller wrote:
> However. I personally like template systems. But how do you want to handle the translations with it? I don't think having different templates for different languages is a good idea as this would destroy all benefits of templates (we would have to manage the same layout multiple times).

The one I originally proposed allows callback functions to be defined.

I.e. instead of

<a href="..."><?php translate('Download'); ?></a>

you write

<a href="...">func_translate(Download)</a>

within a template, this is quite viewable and editable and the string 
translations can still be kept in a central place.