Re: A complete summary of doc.keliglia.com status

Gabor Hojtsy wrote:

Welcome here :) :)

1 - The server: --------------- Guillaume Plessis is supposed to install the server as soon as he can. He will do it on his spare time, and knowing him well, I know that he's always busy with his official work. He was on holiday lately and we didn't want to make him work again. In short, the official server will be online one (sweet) day. While waiting for this, Yannick (and Guillaume) is providing us his personal server without any restriction (only for sudo access, sure). Topic closed (?) :)

If Yannicks machine can bear with the traffic sparkled by this effort, then it will be fine for some time, let Guillaume rest :)

This machine has been supporting me since 2001, I think it's okay ;)

2 - The unofficial website: --------------------------- Yannick (mostly), Guillaume (admin) and I have been developping a first draft since last week. The url is : http://doc.keliglia.com/ This website is still messy (a lot of french comments, redundancy, etc) and I was planing to clean it out before making it public. (Vincent, I'll kick you from #phpdoc as soon as I get back online :p)

This address is going to be doc[s].php.net. What do you think: should we ask systems@ to set these domains up to point to the current server and then reconfigure if the new server is up? Having the server under the php.net umbrella would help in idetifying logged in PHP.net users (and would shed some more official light on the project :).

Go for it, can you please ask them to do so ? Keliglia IP is always the same : 81.57.253.132

What was done so far ? * templates : they are derived from the official websites. Seems like we're not going to use them, but Yannick have made a lot of efforts to make them XHTML 1.0 strict compliant. Maybe the official sites can use them so that we won't be wasting any effort ? :)

The official PHP.net layout has two versions now (a CSS-P one used on two and one column pages, and a table based one used on the manual pages and on the homepage). My efforts to create a CSS-P based layout for the manual pages have been stopped by some IE bugs discovered, which I had no time to find workarounds for. But if you check the download page for example, it is superclean HTML with CSS applied: http://php.net/getphp So far only I have been objecting against the php.netish look for this joint effort, since I am a bit sick with it, and I do think that it should not be that different for the different doc projects. And what is most important, it will not work if I pick hu.docs.php.net, which is not supposed to be tied to any of the projects.

So what do you want for the new website ? I'm ok with changing the design.

* revcheck : I rewrote everything from scratch to integrate an sqlite database to handle it. The idea is : - a single database per documentation (pear, smarty, ..) - the ability to build the database for several languages at once. Why did I use sqlite instead of simply generating static HTML pages ? There are a lot of reasons : * when we first started to use this system on phpdoc-fr, the generated

    page was really huge, and made my browser crash several times. (now
    we're 99% uptodate, so this is not a probelm anymore for the french translation :))

* I wanted to be able to dynamically extract the outdated files for a

    particular translator, without having to run revcheck.php for every dude.
    My idea is to have a login system for every @php.net member, to be able
    to provide a karma system over the website (who is able to edit the news ?
    who can drop the comments ?) Sqlite was a clear answer to me.

It seems like Gabor wasn't to happy with sqlite, what about it now, with the explanations ?

It is nice to get out data per contributor, so it would probably fit. But the revcheck code should support printing the full page version (my browser have not crashed on it, although we have thousands of untranslated files :)

I'll take care.

Since I have a copy of the code, I have seen you are using mysql too. I would suggest you stick to sqlite instead, since livedocs will run on that anyway, and it will be easier for future contributors to help, if only a single database type should be dealt with.

Yup, we used MySQL because we needed to set up the RFC stuff quickly, but I'll change it to use Sqlite as soon as we have a final decision for this.

Yannick used jpgraph to provide some graphic for revcheck. We can compare the different translation status with a single look to a picture, or we can see the detailed status of a translation with another one.

The graphs are nice, the text on them should be fixed :) I'll do that.

Seems to be fixed, but this wasn't reported to keliglia's mailing list because of some of my tests on commitinfo.pl. Do you think we should redirect the commits email to this mailing list ?

Also, I'm an optimistic guy, I believe that if someone reads a translation of the manual, and sees a warning claiming that this translation is outdated. This someone can help us updating the translation if we provide a simple way to do it. (see the phpdoc/RFC for the findings about a visual editing utility)

That is a bit too optimistic with current conditions, but Christian is working on something towards making this possible (his main problem is our entity usage).

What is the project web page ? Maybe Nuno and him can join efforts ?

Maybe we can create an RFC dir in each documentation repository to discuss the particular topics (restructuring the install part for phpdoc, using phpdocumentor for peardoc, ..), and an RFC dir in the website CVS module to discuss some global issues (how do we document a class ? I know Steph has been waiting for an official and global answer since ... too much time). We could also drop a fresh XML DTD for the RFCs, to add more informations, something like : <rfc id="xx"> <title>title</title> <topic>short description</topic> <content> <para>

    plop plop plop

</para> </content> </rfc> (or whatever structure you want) We will extract the various commit messages to provide a summary of changes. Anyway, waiting for comments on this (it's an RFC :D).

I don't know how this is done in separate projects (PEAR, GTK?)

Me neither to be honnest. Guys ?

* Splitted the site ------------------- Actually we have : The unified site : http://doc.keliglia.com/ A per documentation site : http://pear.doc.keliglia.com/ for example The idea behind this is *not* to separate the efforts at all. We're all in the mood of sharing our knowledge (pear know well how to document OO Api), our new stuff (livedocs)... The idea is to be able quickly to access a documentation specific information. For example, I'm Mr Foo, and I'm only interested in gtk docs. I don't want to read all php, pear, smarty stuff when I'm seeking an information on the website. SO I just have to prepend "gtk." to the general URL to see GTK informations. We did this with a vhost system, but sure, we can do it via folders, or whatever you'd like to.

I don't have a problem with having subdomains, if that does not need too much setup on the php.net side. The ideal way is that systems@ sets up our doc subdomain once, and it will work in the future regardless of how many subprojects or languages are added. I don't know the technical details of DNS resolving for wildcard DNS.

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. 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.

Still investigating, I'll reply back to this later. I feel like it will be a shity day at work today, dunno if I'll be able to discuss a lot of stuff .. :/ didou