Re: Some ruminations -- Re: [PEAR-DOC] Upgrading to Docbook 4.3

--- Norbert Mocsnik <pear-doc@mocsnik.hu> wrote: > Jesus M. Castagnetto wrote: > > Apart from moving to Docbook 4.3, we should also > think > > on moving the translations out of the main > (English) > > documentation and into their own CVS dirs. It will > > make life easier in the future and now it will be > less > > painful than later, we should repeat the pain that > > happened when that was done in PHPDOC, the sooner > the > > better. > > Could you make it clear why translations should be > moved out of the main dir for those ones (including > me) who have no clue about it? Mainly from the point of view of managing the documentation and the building of the manuals. If you see the archives of PHPDOC [1], it came a time where the directory structure containing all translations inside one single 'phpdoc' dir got on the unmanageable side, and back there there were only a handful of translations, not the big number we have now in the PHP manual (see all the phpdoc-* dirs in cvs.php.net). And even there it took some time until the decision was made for doing the split [2]. There were also some cases in which there were people commiting to the wrond subdirectory, messing up the 'en' subdir several times and having to be manually reverted, or people creating translations inside 'en' instead of in a sibling subdir. The creation of the separate translations was also good in terms of the way each translation group handled its own commits. Karma was separated so someone working on phpdoc-es (for example) will not be able to mangle the phpdoc docs if he/she has only karma for phpdoc-es. Also when building the manual this was easier, and simpler to have a log of which manual built failed, etc. Finally, there is inconvenience of getting more than in needed when checking out from CVS. As it stands now, if I check out peardoc, I not only get the english docs but also all the other translations. Fortunately now I have cable modem and I do not have to pay by how much traffic I generate, but I am not sure everyone is in the same situation. We are not at the point where PHPDOC had to split the translations into its own directories, but perhaps we should not wait until we get there. Also, most of the scripts, etc. for keeping the translations in step with the main manual are there in the phpdoc dir already. HTH clarify why I was proposing this. Cheers. [1] See the thread at http://marc.theaimsgroup.com/?l=phpdoc&m=98949210523286&w=2 [2] Thread at http://marc.theaimsgroup.com/?l=phpdoc&m=102054770617498&w=2 ===== --- Jesus M. Castagnetto <jmcastagnetto@php.net> __________________________________ Do you Yahoo!? SBC Yahoo! - Internet access at a great low price. http://promo.yahoo.com/sbc/