Re: pod2.perl.org! (was Re: Perl core documentation translations)

--0016e64be14cda4ff1047558ee05
Content-Type: text/plain; charset=ISO-8859-1

On Wed, Oct 7, 2009 at 10:56 AM, Enrico Sorcinelli <
[email protected]> wrote:

> Hi Adriano,
>
> happy to hear from you! :-)
>
> 2009/10/6 Adriano Ferreira <[email protected]>:
> >>
> >> I also contacted several times Adriano Ferreira (the current
> >> Pod::Perldoc maintainer) since the module have to cooperate with POD2
> >> packages.
> >> 5.10.1 Pod::Perldoc breaks POD2:: packages and also latest CPAN
> >> Pod::Perldoc contains several little bugs (I sent a patch to p5p
> >> list).
> >> Unfortunately he didn't respond yet to me :-\
> >
> > I am listening. My basic point is that we need a base package like
> > POD2::Base which is optionally loaded by perldoc and not part of p5p
> core.
> > Why a base package? So we can sophisticate language support, with the
> > minimum fuss for Pod::Perldoc code which is rather clunky by now. Adding
> to
> > the top of it (without a plugin-like structure) won't make it better, but
> > instead harder to maintain and evolve.
> > Why not part of p5p core? Because p5p don't want or need more modules to
> > take care of. Look how CPAN.pm has a myriad of useful optional modules
> which
> > are not part of the core, and it still works.
>
> I agree with you on POD2::Base (or simpy POD2.pm), but IMHO it should
> be in the core! :-)
>
> The fact is that without POD2::Base, starting from Pod::Perldoc ( v >
> 3.14_2), the POD2 translation packages don't work. I already sent to
> p5p and to you a post regarding that
> (http://www.nntp.perl.org/group/perl.perl5.porters/2009/09/msg150704.html
> ).
>
> The main reason is that starting from Pod::Perldoc 3.14_03, the
> translators are objects or, to better explain, must have new() and
> pod_dirs() function/methods.
>
> So, the ways to solve the problem are:
>
> 1) update POD2:: packages by adding those methods (I done as
> workaround for POD2::IT)
> 2) require POD2::Base
> 3) downgrade Pod::Perldoc, by re-adding pod_dirs() method
>
> I think that  the 2nd is the best solution, once POD2::Base will be in
> the core :-)
>
> POD2::Base also should manage (by loading correct POD2::<LANG> module)
> all localized strings used by Pod::Perldoc and others most used Pod::
> modules (like Pod::HTML that match "=head1 NAME" lines)
>

That's a can of worms. I saw people trying that before (
http://search.cpan.org/~pfeiffer/Time-Decimal-0.06/POD2/EO/Time/Decimal.pm)
and I tried myself (
http://search.cpan.org/~ferreira/POD2-Base-0.043/lib/POD2/PT/POD2/Base.pod)
-- the best compatible way to do it these days is eg

=head1 NAME/NOMO    (for Esperanto)

=head1 NAME/NOME    (for Portuguese)

I think we could bypass the need for these language-specific matching, if we
started to use the
old English patterns  =head1 NAME   AND an annotation in a X<> Pod markup
like

=head1 NOME
X<^pod:name>

But that needs to be implemented yet (and in a better way than Pod::Perldoc
does a lot of things today by trying to parse Pod itself when it should rely
on Pod::Simple or a real Pod parser).

The same goes for marking the section of Perl builtins in internationalized
   perlfunc.pod

I think this idea has a lesser impact and a better chance to be introduced
to Perl web resources like search.cpan.org

About POD2::Base or POD2.pm in core, I still think Pod::Perldoc could warn
when -L gets used and neither the language-specific POD2::<lang> namespace
or the base could not be found, telling the user it should install them.
Internationalized distributions would add this base to the perl distribution
modules, avoiding this hassle for first-time users.

Adriano

--0016e64be14cda4ff1047558ee05--