From: Hojtsy Gabor
> Some time ago, we tried to discuss our revision chechking
> ideas here on the list, but the discussion was pointless
> as there were no actual script and implementation to talk
> about.
As you know, I have been against a revision checking system. It is
useless to write a revision number into the documentation.
> Now here is a working example of the Revision comment system,
> we were talking about. The revision comment syntax, as we
> discussed is:
>
> <!-- EN-Revision: 1.34 Maintainer: tom Status: ready -->
>
> or for unknow revisions:
>
> <!-- EN-Revision: n/a Maintainer: tom Status: working -->
>
> The EN-Revision is the corresponding revision from the
> english tree, the Maintainer is the person, who actually
> maintains (is reponsible for) the file, status can be
> anything, it is not restricted.
What will you do with maintainers (responsibles) for a particular
file if he is inactive for 15 months and two weeks. I can see this
in the German documentation (look at [en|de]/functions/pcre.xml and
de/Translators). There is a maintainer for the German version and
nothing happens.
> The script walks through the en dir in phpdoc and tries
> to find the corresponding files in the translations dir.
And what will your script tell you. Hartmut looks into every
<refpurpose /> element and looks for differences. If he could
detect a difference, he assume that this particular file is already
translated. The scripts from Hartmut will mostly fail if someone
translate only one function in this particular file.
> There are lists for untranslated files and files without
> revision comments.
If you validate a special language (except en) you can see a list of
untranslated files. I don´t know what we will gain from revision
comments.
> The best thing is the colored revision table, where you
> can find all the information as in /~rasmus/status.php,
> but many more:
>
> - the exact revisions, and number diffs
> - some size diffs (not exact, as the en and <tr> languages used)
> - date diffs (this is the only one that /~rasmus/status.php
provides)
>
> A real world example is attached (the actual hungarian files).
I think revision numbers and comments are not sufficient.
> Hope this helps to start a discussion about the usefullness
> of this revision comment syntax...
It may be working in the hu tree, there is only one maintainer :)
This would not work in the German manual, because we have many
maintainers and not every maintainer is active. So the only solution
to this dilemma is, every translator have to lookup the changes
(cvs.php.net) in the en tree back to the time the translation was
modified.
I say it again, revision numbers and comments are useless for every
translation. All information you need is in http://cvs.php.net/ -->
phpdoc -->[en|de|hu ...]. There have been discussions to split every
file in files which contain only one function description. But if we
can do this we should reorganize the function reference first. The
next days Hartmut will be back. The Linux Beer Hike 2001 in Belgium
is over.
-Egon
