From a.r.ferreira at gmail.com  Mon Sep  3 14:46:54 2007
From: a.r.ferreira at gmail.com (Adriano Ferreira)
Date: Mon, 3 Sep 2007 18:46:54 -0300
Subject: [Roma.pm] Request for Comments - Improving perldoc
Message-ID: <73ddeb6c0709031446v2cccbd18w8f7f3bd5f01cef8f@mail.gmail.com>

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pod2-it.diff
Type: application/txt
Size: 1860 bytes
Desc: not available
Url : http://mail.pm.org/pipermail/roma/attachments/20070903/f4e77990/attachment.bin 

From a.r.ferreira at gmail.com  Tue Sep  4 07:43:23 2007
From: a.r.ferreira at gmail.com (Adriano Ferreira)
Date: Tue, 4 Sep 2007 11:43:23 -0300
Subject: [Roma.pm] Request for Comments - Improving perldoc
In-Reply-To: <73ddeb6c0709031446v2cccbd18w8f7f3bd5f01cef8f@mail.gmail.com>
References: <73ddeb6c0709031446v2cccbd18w8f7f3bd5f01cef8f@mail.gmail.com>
Message-ID: <73ddeb6c0709040743k2eab4dc6o34c1819a3e1b3917@mail.gmail.com>

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
>
>