Please take the time to read this long example, as it
will help understand the usage of Revision comments.
Simply think of the Revision comments as the splitup
of the Translators file. Lets see a longer example,
now with the de tree, for Egon to be comfortable.
An extract from de/Translators:
-------- pear --------------------------------------------------------------
about.xml Mark Kronsbein fertig (bis V. 1.1)
See the Revision comments parts for this file:
EN-Revision : 1.1
Maintainer : Mark Kronsbein (mk if we use CVS user names)
Status : fertig (status names are not restricted, can be german)
See the complete Revision comment for this file:
<!-- EN-Revision: 1.1 Maintainer: mk Status: fertig -->
we can also use:
<!-- EN-Revision: 1.1 Maintainer: mk Status: ready -->
as there is no agreement on the status flags, but
maybe we can stick to english ones.
So this part is exactly the same infomation as stored in
de/Translators. Then why it is better to put it into the files?
- a unified syntax for all languages (Translators are not unified)
- should be put in the file itself, and it moves with the
file (there is no need to have a Translators file with
it, or look into any other file, to see these informations)
- only one update per commit
- can be easily processed by a script
So this is not a new thing in life, it is just another
place and format for the information, you at the de
group already placed in the Translators file.
This way you loose the Translators file
"information at a glance", as it is not so convinient
to always update the file itself, and the Translators
file too. Especially this is why the Revision comments
born, to get rid of the too many updates.
Now you have no table to look into for all the information
about the files as you have the informations split up
in the files.
BUT we have a script named "revcheck.php" to generate
a summary table for the de translation.
Think of "revcheck.html" as a "partial" replacement
of de/Translators. It is not a full replacement,
because the Translators list, and other supplmental
information is still in the Translators file.
Now see what revcheck.html provides you about the
pear/about.xml extracted above (the file is now
named revcheck_de.html, and is only an extract,
to make things clear, what we are talking about).
Again, try to think about revcheck.html as a
HTML version of Translators. Although it is not
just simply a text->HTML conversion of Translators,
it provides much more.
This table extract talks about de/pear/about.xml
With revcheck.html you know:
| The english revision used to translate the file
| is 1.1, but the current english revision is 1.3,
| so there is a diff of two revisions between the
| english revision used to translate the file,
| and the actual english file.
| If you would like to update the file, click on
| the filename (link), and see the diff of these
| two english versions. This is exactly what you
| need to update.
Without revcheck.html you can:
# If you would like to update the file, you
# need to find out the used revision from the Translators
# file, then the actual one, from your english checkout's
# about.xml (in the $Revision CVS comment). Then you need
# to download the old version, and make on offline diff,
# or navigate to the online diff tool and give the two
# revision numbers manually. This is much harder, than clicking
# a link :)) Without any revision number, you only have the date
# of the de/pear/about.xml file, so you need to guess what
# was the actual revision that time in the english tree,
# and assume that it was used (and not eg. a week old one)
# when the translated file was made.
Some more fields in which revcheck.html can help you:
| While doing a size diff with the used and actual
| english file is time consuimg (cvs need to communicate
| with the server and checkout the used english file),
| printing a diff with the english and translated file
| can be fast, and maybe helps a bit.
| At last you can see the dates, you base your work on now.
| The actual about.xml is 14 days old, but the de verion is
| 52 days old. It is 38 days behind the english version.
I admit, that the last one is actually a cheat,
because adding the Revision comment to the file
changed the files age to zero days, so I manually
modified the revision_de.html file to contain the
correct dates, but this is only a problem once, when
you first add the comment, then the information about
age will be correct.
The maintainer and status text are just copied
here from the file.
In addition, the revision checking script colors the files
according to the revision diffs and numbers. If the used revision
is real old, then the color is red, if the revision is
unknown, then the color is orange, if the revision is
a bit old, the color is yellow, if the file is actual,
the color is green. This also helps spotting out
untouched files, and start the updates.
This file is colored yellow, because it is a bit old
(2 revisions behind).
With the script, you can also generate a revcheck.html
only containing the files, you are reponsible for.
The missing files, and the files without revision
comments are also listed as a side effect.
Goba
Title: PHPDOC Revision-check
|
| Translated file |
Revision |
Size in kB |
Age in days |
Maintainer |
Status |
| en |
de |
diff |
en |
de |
diff |
en |
de |
diff |
| de/pear/ |
|---|
| pear/about.xml |
1.3 | 1.1 |
2 |
1 |
1 |
0 |
14 |
52 |
-38 |
mk |
ready |
|
