RE: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
> -Original Message- > From: Philip Olson [mailto:[EMAIL PROTECTED] > Sent: Friday, October 12, 2007 3:30 AM > To: [EMAIL PROTECTED] > Cc: PHPdoc List; Hannes Magnusson > Subject: Re: [PHP-DOC] EN-Revision comments Vs Docbook > revision attributes > > > Personally I'm unable to throw my vote towards any particular > method at this time but feel we're getting somewhere and that > this topic won't be forgotten. Ideally even more people will > weigh in with ideas, especially translators, for how best to > approach this. There are several good ideas floating around > so to summarize them (including my thoughts): > > --- > (A) The proposal with manually updated revision numbers. One > for minor, another for major. (Hannes) > > I don't see forgetfulness (which would no doubt happen from time to > time) as a solid enough reason to scrap this idea entirely > because we have a strong enough peer review to combat that. > Overall it's a nice proposal but see below. > > (B) Automatic revision increments by default, with ability to > manually disable the increment per commit. (Leonardo) > > This is my current favourite (but how best to implement?) as > it's essentially the best of both worlds. > > (C) Use the CVS commit message to designate status, and use > scripts/ tools to parse. (Jakub) > > A similar idea here is we could (in addition to B above) do > this to mark 'critical' commits in the message, and then a > tool would let translators know which files still require > these critical fixes. In fact, we may even consider 'hiding' > these pages (via the build) by showing EN/ versions until > they are in fact translated. > > (D) Have it all automatic, as done currently. (Nuno) > > Hopefully the above thoughts help ease these concerns. > > (E) ? (?) > --- > > And even though it's a good start, what we decide here won't > be the magical bullet that'll solve our translation problems. > I can't speak from experience but strongly urge all > translators to think about this entire topic and brainstorm > for methods to help better manage the translations. Is it > simply a lack of volunteer time? Or is the difficulty of > working with the manual sources the main problem? Do we need > better tools? Is file ownership ever an issue? How does > Japanese bionic man Masahiro do it all? And while we're at > it, let's ensure the following is correct and wise: > >http://doc.php.net/php/dochowto/chapter-translation.php > > And regardless of what we do here, the idea of declaring > outdated translated text as outdated (and linking to en/) via > the build system will be done. Livedocs did it, and PhD will > too. Right Hannes? ;-) > > Regards, > Philip Hi ! Since I do not know deeply all the intricacies of CVS and PhD, I cannot opt for one of the proposals above. (C) looks too 'artificial' in my opinion. When I first joined the team as a translator it was rather difficult and it took me some time to figure out how everything works. It would be nice to make the Howto more detailed and more 'newbie oriented' if someone has the time, of course. Also in the beginning it was difficult for me to figure out the status of the entire translation. The page at http://doc.php.net/php/ro/revcheck.php showed outdated information although we made commits to the 'ro' tree. Only when I figured out how to run 'revcheck' locally I got the real picture. Is it difficult to put this script somewhere on cvs.php.net so that it always checks the latest data? These are my thoughts for now. Best regards, Simion.
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
Personally I'm unable to throw my vote towards any particular method at this time but feel we're getting somewhere and that this topic won't be forgotten. Ideally even more people will weigh in with ideas, especially translators, for how best to approach this. There are several good ideas floating around so to summarize them (including my thoughts): --- (A) The proposal with manually updated revision numbers. One for minor, another for major. (Hannes) I don't see forgetfulness (which would no doubt happen from time to time) as a solid enough reason to scrap this idea entirely because we have a strong enough peer review to combat that. Overall it's a nice proposal but see below. (B) Automatic revision increments by default, with ability to manually disable the increment per commit. (Leonardo) This is my current favourite (but how best to implement?) as it's essentially the best of both worlds. (C) Use the CVS commit message to designate status, and use scripts/ tools to parse. (Jakub) A similar idea here is we could (in addition to B above) do this to mark 'critical' commits in the message, and then a tool would let translators know which files still require these critical fixes. In fact, we may even consider 'hiding' these pages (via the build) by showing EN/ versions until they are in fact translated. (D) Have it all automatic, as done currently. (Nuno) Hopefully the above thoughts help ease these concerns. (E) ? (?) --- And even though it's a good start, what we decide here won't be the magical bullet that'll solve our translation problems. I can't speak from experience but strongly urge all translators to think about this entire topic and brainstorm for methods to help better manage the translations. Is it simply a lack of volunteer time? Or is the difficulty of working with the manual sources the main problem? Do we need better tools? Is file ownership ever an issue? How does Japanese bionic man Masahiro do it all? And while we're at it, let's ensure the following is correct and wise: http://doc.php.net/php/dochowto/chapter-translation.php And regardless of what we do here, the idea of declaring outdated translated text as outdated (and linking to en/) via the build system will be done. Livedocs did it, and PhD will too. Right Hannes? ;-) Regards, Philip
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
Nuno Lopes написа: > I don't like this idea because the revision doesn't get bumped automatically. I think there'll be more problems that the little efforth of the translators to bump a no-op revision. Please remember that not everybody that contributes documentation belongs to the phpdoc team and thus isn't aware of our latest practices. So, automatic things are the best things (tm). Nuno Well, in case there's a special "by default" level, it will not break the automatic bump of the revision. That level could be the "minor" one proposed by Hannes, for example. On the contrary, when a critical (major) change is introduced, it's important to tell the translators to pay much more attention on it. I believe major changes are important enough to spend some 2-3 seconds on tagging/commenting them accordingly. It's a matter of communication and respect between us. -- Kouber Saparev http://kouber.saparev.com
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
Hannes Magnusson написа: On 8/30/07, Philip Olson <[EMAIL PROTECTED]> wrote: On Aug 18, 2007, at 8:42 AM, Fernando Correa da Conceição wrote: Hannes Magnusson escreveu: Hello all Was there any specific reason why this "EN-Revision" comment magic was chosen over the Docbook revision attribute? If there's a better way then let's do it... please propose exactly how it'd work and what it would look like. We'd also need to adjust all the translation scripts within docweb (and scripts/) before/while implementing. (See attached patched for function.strpos on how exactly it will look in the XML) The rules would be the same as CVS Revision, just manually bumped. When not to bump: - WS fixes - (non-important) typos changes - (non-important) grammar changes - Totally irrelevant changes for translations ... When to bump minor version (after the dot): - Minor content fixes - Important typos (referring to wrong function for instance) - Example fixes ... When to bump major version (before the dot): - Security fixes (in examples or text recommendations..) - When adding new section to a page - Otherwise major changes Just use your commonsense when bumping major/minor version. The difference in bumping major vs minor revisions is how the user will see the difference. For instance, if a translation is couple of minor revisions old the end-user will see tiny little yellow warning stating "this translation is little old, no _important_ changes have been done though". If the translation is a whole major revision old the end-user will see a big fat red warning: "This page is out of date! Please consider to view the English version!" -Hannes Although it should not bother the current work of English writers, the idea of telling the end-user that something is out of date and that, either a minor or a major change was introduced, is great. It is important to have correct translations and since it's not that easy to maintain all the changes, it's substantial to at least inform the end-user. I guess it would increase the build time, since a diff might be needed for each file and not just a simple check whether a file is present or not. -- Kouber Saparev http://kouber.saparev.com
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
Hannes Magnusson wrote: > The rules would be the same as CVS Revision, just manually bumped. What about taking similar concept as with PHP source? I.e. marking whether the change is translatable or otherwise in the commit message. Then we can bind some scripts (e.g. scripts/diff_en_rev.php) to these messages. Jakub Vrana
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
On 06/10/2007, Hannes Magnusson <[EMAIL PROTECTED]> wrote: > On 10/6/07, Nuno Lopes <[EMAIL PROTECTED]> wrote: > > I don't like this idea because the revision doesn't get bumped > > automatically. I think there'll be more problems that the little efforth of > > the translators to bump a no-op revision. > > Is your time more worth than the time of 29 translators combined? > Selfish prick! :) > > Bumping it automatically is the problem, not the solution. I don't think Nuno's message implies that the editor's time is somehow more important than translators' time (tacitly or otherwise). I think I share his point of view, which is not to flat-out refuse the new system proposed, for whatever reason, but to stop for a moment and think how it would work in reality before it's implemented. By the way, it's nice to have proposals like this one; much is being done lately to improve things and that's really great, so thanks Hannes, Philip and everyone else :). Back to the matter at hand, I handle, for example, a reasonable amount of translations in the ES tree (1000+ at the moment), and while it's a bit too much to keep up with sometimes, I wouldn't say that my time is being wasted or something like that just because 1, or 10, or 100 documents introduced typo fixes that don't matter to me in the last commit. I personally find that being as sure as I can that my translations are really in sync and correct with the latest EN versions is more important that the time I think I would save by this new system. I completely understand the concern of not incrementing the revision numbers automatically. For example, the routine I follow when I update a translation starts with updating the revision number. I've done this *a lot*. Now, you would think that my mind would make me follow this step automatically every time, but still there are cases where after updating a group of translations, I notice that I didn't update the revision number in one or more of them. Now, this is just my experience as a translator. Surely this would not be exactly the same for editors. Perhaps the act of editing the EN documents is different from updating translations and the possibility for missing the number update is lower for editors, I don't know, but we are all humans, and sometimes we err... Would I welcome the chance of not having to update translations when only irrelevant changes have been made? Absolutely, but only if I know for sure that my documents are really up-to-date and there's no possibility for an important change being introduced that I never knew about. So, my conclusion would be, can we think about this a little more? Perhaps having some sort of pre-commit hook that lets the editor choose which documents should not imply a revision increment, and always incrementing the revision number by default, unless the editor explicitly states otherwise? Thanks, Leonardo
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
On 10/6/07, Nuno Lopes <[EMAIL PROTECTED]> wrote: > > > > Hannes Magnusson escreveu: > > > >> Hello all > > > >> > > > >> Was there any specific reason why this "EN-Revision" comment magic > > > >> was > > > >> chosen over the Docbook revision attribute? > > > > > > If there's a better way then let's do it... please propose exactly > > > how it'd work and what it would look like. We'd also need to adjust > > > all the translation scripts within docweb (and scripts/) before/while > > > implementing. > > > > (See attached patched for function.strpos on how exactly it will look > > in the XML) > > > > The rules would be the same as CVS Revision, just manually bumped. > > I don't like this idea because the revision doesn't get bumped > automatically. I think there'll be more problems that the little efforth of > the translators to bump a no-op revision. Is your time more worth than the time of 29 translators combined? Selfish prick! :) Bumping it automatically is the problem, not the solution. We have almost 30 translations, and only 1 up2date. Seriously, the Japanese translation is the only translation with over 50% content up to date. Currently we have no way of knowing if the French translation is missing critical fixes or if it simply needs to bump its revision after the bunch of English-only-fixes to the docs the past months. Given the fact phpdoc has been pretty much sleeping for the past few months I have serious doubts that the French translation really is that outdated. If we bumped the (major&minor) revision manually we could (more) accurately determine if the translation was really out of date and warn the end-user if it really is. > Please remember that not everybody that contributes documentation belongs to > the phpdoc team and thus isn't aware of our latest practices. So, automatic > things are the best things (tm). Whoever commits the patch is responsible for it and should make sure its "phpdocified" (proper ws, markup inline with the current recommendations, entity usage...). -Hannes
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
> > Hannes Magnusson escreveu: > >> Hello all > >> > >> Was there any specific reason why this "EN-Revision" comment magic > >> was > >> chosen over the Docbook revision attribute? > > If there's a better way then let's do it... please propose exactly > how it'd work and what it would look like. We'd also need to adjust > all the translation scripts within docweb (and scripts/) before/while > implementing. (See attached patched for function.strpos on how exactly it will look in the XML) The rules would be the same as CVS Revision, just manually bumped. I don't like this idea because the revision doesn't get bumped automatically. I think there'll be more problems that the little efforth of the translators to bump a no-op revision. Please remember that not everybody that contributes documentation belongs to the phpdoc team and thus isn't aware of our latest practices. So, automatic things are the best things (tm). Nuno
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
On 8/30/07, Philip Olson <[EMAIL PROTECTED]> wrote: > > On Aug 18, 2007, at 8:42 AM, Fernando Correa da Conceição wrote: > > > Hannes Magnusson escreveu: > >> Hello all > >> > >> Was there any specific reason why this "EN-Revision" comment magic > >> was > >> chosen over the Docbook revision attribute? > > If there's a better way then let's do it... please propose exactly > how it'd work and what it would look like. We'd also need to adjust > all the translation scripts within docweb (and scripts/) before/while > implementing. (See attached patched for function.strpos on how exactly it will look in the XML) The rules would be the same as CVS Revision, just manually bumped. When not to bump: - WS fixes - (non-important) typos changes - (non-important) grammar changes - Totally irrelevant changes for translations ... When to bump minor version (after the dot): - Minor content fixes - Important typos (referring to wrong function for instance) - Example fixes ... When to bump major version (before the dot): - Security fixes (in examples or text recommendations..) - When adding new section to a page - Otherwise major changes Just use your commonsense when bumping major/minor version. The difference in bumping major vs minor revisions is how the user will see the difference. For instance, if a translation is couple of minor revisions old the end-user will see tiny little yellow warning stating "this translation is little old, no _important_ changes have been done though". If the translation is a whole major revision old the end-user will see a big fat red warning: "This page is out of date! Please consider to view the English version!" -Hannes Index: ja/reference/strings/functions/strpos.xml === RCS file: /repository/phpdoc-ja/reference/strings/functions/strpos.xml,v retrieving revision 1.10 diff -u -p -r1.10 strpos.xml --- ja/reference/strings/functions/strpos.xml 11 Aug 2007 04:15:46 - 1.10 +++ ja/reference/strings/functions/strpos.xml 6 Oct 2007 11:23:11 - @@ -1,7 +1,6 @@ - -http://docbook.org/ns/docbook"; xml:id="function.strpos"> +http://docbook.org/ns/docbook"; xml:id="function.strpos" revision="1.14"> strpos æååãæåã«ç¾ããå ´æãè¦ã¤ãã Index: en/reference/strings/functions/strpos.xml === RCS file: /repository/phpdoc/en/reference/strings/functions/strpos.xml,v retrieving revision 1.14 diff -u -p -r1.14 strpos.xml --- en/reference/strings/functions/strpos.xml 20 Jun 2007 22:25:31 - 1.14 +++ en/reference/strings/functions/strpos.xml 6 Oct 2007 11:23:11 - @@ -1,6 +1,6 @@ -http://docbook.org/ns/docbook"; xml:id="function.strpos"> +http://docbook.org/ns/docbook"; xml:id="function.strpos" revision="1.14"> strpos Find position of first occurrence of a string
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
On Aug 18, 2007, at 8:42 AM, Fernando Correa da Conceição wrote: Hannes Magnusson escreveu: Hello all Was there any specific reason why this "EN-Revision" comment magic was chosen over the Docbook revision attribute? If there's a better way then let's do it... please propose exactly how it'd work and what it would look like. We'd also need to adjust all the translation scripts within docweb (and scripts/) before/while implementing. Regards, Philip
Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes
Hannes Magnusson escreveu: Hello all Was there any specific reason why this "EN-Revision" comment magic was chosen over the Docbook revision attribute? As I see it we could safe our translators _alot_ of work by manually bumping revision whenever the changes done in the en docs need re-translation. This would mean that all the WS, typo, grammar and other English specific bugs won't bump revision => nothing for translators to fix, they shouldn't be forced to updated some tags. The only argument against it (I could find) is "more work for en doc writers". Heh? Right. That argument is so selfish that if anyone so much as mentions it I'll hunt the person down and throw snowballs at him :) Choosing when to bump revision and when not takes under 2seconds. Compared to the 5seconds[1] it takes _every_ translator to figure out if there was any real change or if he just needs to bump his EN-Revision (another few seconds)... This will also allow us to more accurately determine if a translation is really out of date or not. What do you guys think? [1] Locating and opening the commit. Read the commit message and then review the commit... hmm. That is probably more than 5secs.. -Hannes As an translator, a big +1 for this. Fernando Correa da Conceição.
[PHP-DOC] EN-Revision comments Vs Docbook revision attributes
Hello all Was there any specific reason why this "EN-Revision" comment magic was chosen over the Docbook revision attribute? As I see it we could safe our translators _alot_ of work by manually bumping revision whenever the changes done in the en docs need re-translation. This would mean that all the WS, typo, grammar and other English specific bugs won't bump revision => nothing for translators to fix, they shouldn't be forced to updated some tags. The only argument against it (I could find) is "more work for en doc writers". Heh? Right. That argument is so selfish that if anyone so much as mentions it I'll hunt the person down and throw snowballs at him :) Choosing when to bump revision and when not takes under 2seconds. Compared to the 5seconds[1] it takes _every_ translator to figure out if there was any real change or if he just needs to bump his EN-Revision (another few seconds)... This will also allow us to more accurately determine if a translation is really out of date or not. What do you guys think? [1] Locating and opening the commit. Read the commit message and then review the commit... hmm. That is probably more than 5secs.. -Hannes
