[Roma.pm] Request for Comments - Improving perldoc

[Adriano Ferreira]

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.ferreira at gmail.com> 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
>
>