For now, we're sharing the same files and filtering the rendered HTML if a documentation
type is provided. http://doc.keliglia.com/ is our meeting point, it's the place where
we'll group our efforts, but every language has its particular things, don't forget
it :)
OK, here is the first organizational decision. We have a matrix with projects and languages. Some projects have no languages at all (Livedocs and PECL will not have language specific info). These projects however need to have their howtos (how to set up livedocs, where are PECL extensions documented, etc). So these projects need special files.
mmm, I'm not sure about PECL being a part of this site. Wasn't we about to document it in phpdoc ?
Also there are languages with a desire to put up their own instructions (in their own language probably) on how to help, join the translation, etc. For Hungarian docs, we have two groups, one working on the PEAR stuff (a sole guy) and one group working on the phpdoc stuff, we would need pages explaining the pear doc stuff and the phpdoc stuff (there are different people to ask questions, etc).
So there seems to be a need to put in files for some language (globally accessible for all projects), some project (globally accessible for all languages), and some project+language (only for that project and language).
The first question is how to organize this stuff on the CVS server, and then how to map the files into some sensible navigation. We have a matrix, with entries spanning a row or a column or both (for sitewide info) or just one cell.
hu.docs.php.net, pear.docs.php.net, hu.pear.docs.php.net (or pear.hu.docs.php.net) should pick up the pages and navigation elements relevant for that selection from the matrix.
Since we have livedocs as project on the website, the first idea actually used on keliglia.com will need to be changed. I'm now thinking
about having : PROJECT.docs.keliglia.com/part/LANG*, LANG being optional (Nuno, happy ? ;)). As projects, we'll have :
php
pear
smarty
gtk
livedocs (or live to have live.docs.php.net ;))
As we want to share some parts in some, but not all, projects (livedocs really don't need a revcheck), I think we'll need a function like
is_part_available(), checking for the (project,language,part) called in the top of each script and also used to dynamically generate the navigation. Here's a draft of the function:
An array like :
$matrix = array(
'project' => array(
'part' => bool (is it available in many languages ?)
)
)
// We already defined with a nice 404 handling (or mod_rewrite):
// LANG (default is en)
// PROJECT (default is www)
// PART (from the url)
function is_available()
{
global $matrix;
// we always check if the asked part is available for the project
$return = isset($matrix[PROJECT][PART]);
// and if we've been asked for a particular language, we see if
// the part supports multiple languages
if (LANG != 'en') {
$return = $return && $matrix[PROJECT][PART];
}
return $return;
}
yes, if a project/part have multiple languages, there's a problem if I
call an inexistant for a project, but this is okay since we can detect
it when defining the constants and fallback to "en" ;)
To define constants, we need the following array :
$PROJECTS_AND_LANGS = array(
'type' => array() // empty for livedocs and array("de", "fr", "pt_BR", "ru") for smarty
);
and the following function :
function main()
{
global $PROJECTS_AND_LANGS;
list($vhost, $lang) = get_asked_vhost_and_lang_with_magic_stuff();
if (isset($PROJECTS_AND_LANGS[$vhost])) {
define('PROJECT', $vhost);
if (isset($PROJECTS_AND_LANGS[$vhost][$lang])) {
define('LANG', $lang);
} else {
define('LANG', 'en');
}
} else {
define('PROJECT', 'www');
define('LANG', 'en');
}
}
And sure, to nicely handle all the translated parts :
$LANGUAGES = array(
'code' => array ( // fr
'name' => 'LANGUAGE NAME', // french
'charset' => '', // iso-8859-1(5?)
)
);
This seems to me ATM the best way to have all our information, without
duplicating nothing. The manual part (not livedocs the project, but the test bed) will work well with this also if I didn't miss nothing.
We also can implement a function to generate a bash include file (and even add its name in .cvsignore to be completely happy).
Opinions ?
Mehdi Achour