From: Adriano F. <a.r...@gm...> - 2007-09-04 14:43:28
|
I removed these files from the server. http://ferreira.nfshost.com/perl/POD2-Base-0.02.tar.gz http://ferreira.nfshost.com/perl/Pod-Perldoc-3.14_03.tar.gz as they will be available in a few minutes via CPAN itself. http://search.cpan.org/dist/POD2-Base/ http://search.cpan.org/~ferreira/Pod-Perldoc-3.14_03/ For anyone thinking about giving some feedback, please do. Adriano. On 9/3/07, Adriano Ferreira <a.r...@gm...> wrote: > Hi. > > I am sending this message to this list as you have been responsible > for the patch of Pod::Perldoc that introduced the -L switch and the > auxiliary code of modules POD2::IT (in the CPAN distribution POD2-IT). > > Sorry for not using Italian in this message. But it's better for all of us ;-) > > I am seeking permission and feedback on abstracting the code of > POD2::IT and making the 'perldoc' utility more powerful (with regard > to supporting translated PODs). > > A few days ago I proposed a change to the way -L was implemented and > the external effect was that > > $ perldoc -L it perldoc > > won't fail anymore with POD2-IT-0.11. Even though there is no > translated 'perldoc.pod' - perldoc will find the standard document and > show it. I think this behavior is more friendly. > > rgs' reply to my message - > http://groups.google.com/group/perl.perl5.porters/browse_frm/thread/de387cba4cea0a22/5778258675a33277?lnk=gst&q=Perldoc+adriano&rnum=1#5778258675a33277 > the Change in bleed - http://public.activestate.com/cgi-bin/perlbrowse/p/31762 > > But I was looking after more. For the sanity of Pod::Perldoc, I am > proposing some changes: > > * use objects rather than export functions when loading a language plugin > * augment the API with a method ->pod_dirs > > The rationale for this are: > > * with objects rather than exporting functions, we avoid namespace > pollution and keep open the possibility for multiple translation > packages. Something like: > > $ perldoc -L it -L es foo > > which would mean the use wants at order of preference documentation in > Italian or in Spanish or (the default) English. > > * ->pod_dirs raison-d'etre is just to encapsulate the way to compute > the POD2::<lang> path to look for translated PODs. As it returns a > list and not only one scalar, it leaves open to future extensions: > > + searching specific languages with/without dialects: > > POD2::PT, POD2::PT_BR, etc. > > I want your permission to release a module called POD2::Base which was > based on POD2::IT original code and make it the base of POD2::IT, > POD2::FR and others. The changes in API need to be done as soon as > possible to prevent too much problems with backward compatibilities. > But I think changing this now is a fair game. > > To your appreciation I attached links to a version of POD2-Base > distribution, a patched Pod-Perldoc distribution and a patch to > POD2-IT-0.11 distribution so that you have a feeling for the changes I > am > suggesting. > > http://ferreira.nfshost.com/perl/POD2-Base-0.02.tar.gz > http://ferreira.nfshost.com/perl/Pod-Perldoc-3.14_03.tar.gz > > I have some additional points: > > (1) > POD2::Base is enough for people to start distributing translated docs > by just including them in a standard CPAN tarball installed in the > respective POD2/<lang> directory. > > For basic operation, there is no real need for POD2::<lang> module. Of > course, this does not work for " perldoc -f " which is why the > suggestion is to subclass of POD2::Base as illustrated by the patch to > POD2::IT > > So I could release a new distribution like Module::Which together with > a POD2/PT/Module/Which.pod and have instantly Portuguese documentation > for the module that could be read via " perldoc -L pt ". No need to > coordinate the release of POD2-PT distribution. > > (2) > I have incorporated " print_pod " and " print_pods " methods to > POD2::Base, so that the code of POD2::IT and POD2::FR need no longer > to be repeated and become much small. > > But I don't think this functionality is perfect yet. These call for a > centralized source of info about the translated documents that > contradicts the feature described above. So I think it could be made > different and more flexible. In some next messages, I will try to > illustrate these points. So the permission is also for probably > changing the API even more in the near future. > > Well, sorry for my long intrusion. I am enthusiastic about this > project, but not having a good time about putting my mind together to > better explain and document all of this. So I will ask you to close > your eyes about the current non-documentation of this in the > distributions I am sending. > > I have some hope to ship this changes of Pod::Perldoc together with > perl 5.10 which should be released this month. > > Best regards, > Adriano Ferreira > > |