[Roma.pm] Request for Comments - Improving perldoc

[Adriano Ferreira]

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