çÒÕÐÐÁ :: òÁÚÒÁÂÏÔËÁ/Perl
ðÁËÅÔ: perl-POD2-Base
ÎÁ×ÉÇÁÃÉÑ ÐÏ ÐÁËÅÔÁÍ
çÌÁ×ÎÁÑ éÚÍÅÎÅÎÉÑ óÐÅË ðÁÔÞÉ éÓÈÏÄÎÉËÉ úÁÇÒÕÚÉÔØ Gear Bugs and FR Repocop
POD2-Base-0.043/ 0000755 0000000 0000000 00000000000 11526426444 0013102 5 ustar 00root root 0000000 0000000 POD2-Base-0.043/Changes 0000644 0000000 0000000 00000002170 11526426444 0014375 0 ustar 00root root 0000000 0000000
Revision history for Perl extension POD2::Base.
0.043 Tue Feb 26 2008
- removed 'our' in t/02_basic.t (for 5.005's sake)
0.042 Mon Feb 25 2008
- tweak POD2/PT/POD2/Base.pod
- (temporarily) skips POD test for 5.6
0.041 Sun Feb 24 2008
- POD2/PT/POD2/Base.pod is now a complete
Portuguese translation (without much review)
of POD2::Base docs
0.04 Sat Feb 23 2008
- File::Spec is a prereq now
- one more constructor param: 'inc'
- pod_dirs now accept options ('test')
- pod_dirs now search all over @INC for
"POD2/<lang>/" dirs
- included an example for listing lang-specific
installed files (eg/list.pl)
- included a hoax of a Portuguese translation
for the documentation of this module
0.0301 Fri Feb 1 2008
- warning and vars in PREREQ_PM
- minor POD tweaks
0.03 Tue Sep 4 2007
- rewrote "lib/POD2/Base.pod"
0.02 Mon Sep 3 2007
- first version (after POD2::IT 0.11)
- request for comments at pod2it-translators
and roma-pm mailing lists
POD2-Base-0.043/MANIFEST 0000644 0000000 0000000 00000000561 11526426444 0014235 0 ustar 00root root 0000000 0000000
lib/POD2/Base.pm
lib/POD2/Base.pod
lib/POD2/PT/POD2/Base.pod A PT translation of POD2::Base docs
Makefile.PL
Changes
README
MANIFEST This list of files
t/01_use.t
t/02_basic.t
t/99_pod.t
t/98_pod-coverage.t
t/lib/.exists Existence marker for t/lib/
eg/list.pl
META.yml Module meta-data (added by MakeMaker)
POD2-Base-0.043/META.yml 0000644 0000000 0000000 00000001300 11526426444 0014345 0 ustar 00root root 0000000 0000000 --- #YAML:1.0
name: POD2-Base
version: 0.043
abstract: Base module for translations of Perl documentation
license: perl
author: ~
generated_by: ExtUtils::MakeMaker version 6.42
distribution_type: module
requires:
File::Spec: 0
strict: 0
Test::More: 0
vars: 0
warnings: 0
meta-spec:
url: http://module-build.sourceforge.net/META-spec-v1.3.html
version: 1.3
recommends:
Test::Pod: 1.18
Test::Pod::Coverage: 1.04
ExtUtils::MakeMaker: 6.38
POD2-Base-0.043/Makefile.PL 0000644 0000000 0000000 00000001757 11526426444 0015066 0 ustar 00root root 0000000 0000000
use 5.005;
use ExtUtils::MakeMaker;
my $EUMM_VERSION = eval $ExtUtils::MakeMaker::VERSION;
# note. EUMM 6.38 and later always includes 'author'
# in META.yml fixing compliance with spec
WriteMakefile(
NAME => 'POD2::Base',
VERSION_FROM => 'lib/POD2/Base.pm',
PREREQ_PM => {
strict => 0,
warnings => 0,
vars => 0,
( warnings::compat => 0, ) x!! ( $] < 5.006 ),
File::Spec => 0,
Test::More => 0,
},
($] >= 5.005 ? (
'ABSTRACT_FROM' => 'lib/POD2/Base.pod',
# 'AUTHOR' => 'Adriano R. Ferreira <ferreira@cpan.org>',
) : ()),
($EUMM_VERSION >= 6.31 ? (
LICENSE => 'perl',
EXTRA_META => "recommends:\n" .
" Test::Pod: 1.18\n" .
" Test::Pod::Coverage: 1.04\n" .
" ExtUtils::MakeMaker: 6.38\n"
) :())
);
POD2-Base-0.043/README 0000644 0000000 0000000 00000016512 11526426444 0013767 0 ustar 00root root 0000000 0000000 NAME
POD2::Base - Base module for translations of Perl documentation
SYNOPSIS
use POD2::Base;
$pod2 = POD2::Base->new({ lang => 'EO' });
@dirs = $pod2->pod_dirs;
$re = $pod2->search_perlfunc_re;
DESCRIPTION
This module is an abstraction of the code in POD2::IT and POD2::FR.
These modules belong to the Italian and the French translation projects
of core Perl pods.
Once a translation package had been installed, the translated
documentation can be accessed with:
$ perldoc POD2::<lang>::<podname>
(where <lang> is a language abbreviation like IT, FR, TLH, etc.)
This is guaranteed to work even for older versions of perldoc. It is not
very convenient but always works.
To improve the support to read translated docs, the perldoc utility
(since version 3.14_01) was updated to find translated PODs via:
$ perldoc -L IT <podpage>
$ perldoc -L FR -f <function>
$ perldoc -L TH -q <FAQregex>
(*Note*: this support was shipped together with the recently released
5.10.0 version the Perl interpreter.)
The objective of this class is to provide a minimum base to help
`perldoc' and authors of translation packages to do their job.
SUBCLASSING
If you want to write a translation package (and have some customization
needs), your work may be diminished if you subclass `Pod::Base'.
For example, a minimum example is provided below:
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re { # makes 'perldoc -f' work
return 'Klingon Listing of Perl Functions';
}
1;
And then
$ perldoc -L tlh perlintro
will present you the introduction of Perl in Klingon language (provided
a POD2/TLH/perlintro.pod file was shipped together with POD2/TLH.pm) and
$ perldoc -L tlh -f pack
will find you the Klingon documentation of `pack' (if
POD2/TLH/perlfunc.pod was made available as well).
METHODS
This module has been made into a proper class with a very small API.
new
$pod2 = POD2::Base->new(\%args);
$pod2 = POD2::ANY->new();
The constructor. An actual call might look like this:
$pod2 = POD2::Base->new({ lang => 'tlh' });
where the supported options are:
* "lang"
Specifies the language code we're interested in. This is
required, but can be extracted from the name of a subclass. Read
below.
* "inc"
This is used to override the list of Perl library directories
where POD documents are searched (namely, `@INC'). Most of the
time, you don't want to mess with that. It's handy for debugging
and testing.
It must be an array ref.
If `POD2::ANY' is a subclass of `POD2::Base', the inherited
constructor will work without arguments pulling 'ANY' from the
package name and using it as the intented language code.
Note that use of "inc" in the constructor freezes the list of
library dirs searched by the `POD2::Base' instance. If this is not
used, the up-to-date `@INC' is used at each call of `pod_dirs' (so
that dynamic changes in the Perl library path are taken into
account). That's what we meant with the "Most of the time, you don't
want to mess with that" mentioned above.
pod_dirs
@dirs = $pod2->pod_dirs;
@dirs = $pod2->pod_dirs(\%options);
Used by `Pod::Perldoc' to find out where to look for translated
pods.
The `POD2::Base' default behavior is to find POD2/<lang>/
directories under the current Perl library directories (`@INC') or
the list given as argument "inc" in the constructor.
The supported options are:
* "test"
By default, the return of `pod_dirs' do not include POD
directories which do not exist (tested with `-d'). If an
explicit false value for this option (like `test => 0') is
given, such test is not done and `pod_dirs' includes all
possible candidates POD2/<lang>/ under the library directories.
(Handy for debugging this module. Not much practical use for
anything else.)
search_perlfunc_re
$re = $pod2->search_perlfunc_re;
To implement `perldoc -f <function>' the current code of
`Pod::Perldoc' uses a hard coded string "Alphabetical Listing of
Perl Functions" or the return of this method (in a regexp) to skip
the introduction and reach the listing of core functions. Thus a
translation package with a corresponding translated perlfunc.pod
should define this method to make `perldoc -L <lang> -f <function>'
work properly.
There are other methods documented below. However, they will probably be
superseded in future versions when more general methods to find and
display metadata on translated PODs are designed and implemented.
pod_info
$hashref = $pod2->pod_info;
Used by `POD2::Base' itself. The return contains some metadata on
the translated PODs which is used by the methods `print_pod' and
`print_pods'.
When subclassing, you should override this with the current
information on what POD translations the current package is
providing.
print_pods
$pod2->print_pods;
Prints all translated pods and the corresponding Perl version of the
original files.
print_pod
$pod2->print_pod(@pages);
$pod2->print_pod(); # uses @ARGV
Prints the corresponding Perl version of the original files
corresponding to the pods passed as arguments.
EXAMPLES
POD2::TLH
A slightly extended version of `POD2::TLH' goes like this:
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re {
return 'Klingon Listing of Perl Functions';
}
sub pod_info {
return { perlintro => '5.8.8' };
}
1;
And you may try:
use POD2::TLH;
my $pod2 = 'POD2::TLH';
$pod2->print_pods();
$pod2->print_pod('pod_foo', 'pod_baz', ...);
THE INSTALLED FILES
If you want to find out which language-specific POD files are installed
at your Perl, you could use a code similar to this.
use File::Find;
use POD2::Base;
my $pod2 = POD2::Base->new({ lang => $lang });
my @files;
find sub { push @files, $File::Find::name } if -f },
$pod2->pod_dirs;
print "$_\n" for @files;
In the `POD2-Base' distribution tarball, a script eg/list.pl is included
with an improved version of this code.
The rules of finding POD in .pod, .pm files and others belong to
Pod::Perldoc. So `POD2::Base' do not try to repeat them here.
AUTHORS
Enrico Sorcinelli <bepi at perl.it> (the original POD2::IT code)
Adriano Ferreira <ferreira at cpan.org>
SEE ALSO
POD2::IT, POD2::FR, POD2::LT, POD2::CN, perldoc, perl.
COPYRIGHT AND LICENCE
Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
POD2-Base-0.043/eg/ 0000755 0000000 0000000 00000000000 11526426444 0013475 5 ustar 00root root 0000000 0000000 POD2-Base-0.043/eg/list.pl 0000644 0000000 0000000 00000001132 11526426444 0015002 0 ustar 00root root 0000000 0000000
use strict;
use warnings;
die "usage: $0 lang" unless @ARGV;
my $lang = uc shift;
use File::Find;
use POD2::Base;
my $pod2 = POD2::Base->new({ lang => $lang });
my @dirs = $pod2->pod_dirs;
die "could not find any POD2/${lang}/ directory" unless @dirs;
print "dirs: @dirs.\n";
my @files;
find({
wanted => sub { push @files, $File::Find::name if -f },
},
@dirs );
print "$_\n" for @files;
__END__
=head1 NAME
list.pl - find all files in POD dirs for a certain language
=head1 USAGE
list.pl lang
where B<lang> is the apropriate language code
(eg. CN, PT, IT, FR, etc.)
POD2-Base-0.043/lib/ 0000755 0000000 0000000 00000000000 11526426444 0013650 5 ustar 00root root 0000000 0000000 POD2-Base-0.043/lib/POD2/ 0000755 0000000 0000000 00000000000 11526426444 0014354 5 ustar 00root root 0000000 0000000 POD2-Base-0.043/lib/POD2/Base.pm 0000644 0000000 0000000 00000003776 11526426444 0015601 0 ustar 00root root 0000000 0000000
package POD2::Base;
use 5.005;
use strict;
use warnings;
use vars qw( $VERSION );
$VERSION = '0.043';
use File::Spec ();
sub new {
my $proto = shift;
my $class = ref $proto || $proto;
my $obj = bless {}, $class;
return $obj->_init( @_ );
}
# instance variables:
# lang - the preferred language of the POD documents
# inc - alternate library dirs (if given, replaces the ones in @INC)
sub _init {
my $self = shift;
my %args = @_ ? %{$_[0]} : ();
if ( !exists $args{lang} ) {
$args{lang} = _extract_lang( ref $self );
}
#croak "???" unless $args{lang};
my $lang = uc $args{lang};
$self->{lang} = $lang;
$self->{inc} = $args{inc}; # XXX croak ?! must be array ref
return $self;
}
# $lang = _extract_lang($module);
sub _extract_lang {
my $module = shift;
return $module eq __PACKAGE__ ? undef
: $module =~ /::(\w+)\z/ ? $1
: undef
;
}
sub _lib_dirs {
my $self = shift;
return $self->{inc} ? @{$self->{inc}} : @INC;
}
sub pod_dirs {
my $self = shift;
my %options = @_ ? %{$_[0]} : ();
$options{test} = 1 unless exists $options{test};
my $lang = $self->{lang};
my @candidates = map { File::Spec->catdir( $_, 'POD2', $lang ) } $self->_lib_dirs; # XXX the right thing to do
if ( $options{test} ) {
return grep { -d } @candidates;
}
return @candidates;
}
#sub search_perlfunc_re {
# shift;
# return 'Alphabetical Listing of Perl Functions';
#}
sub pod_info {
shift;
return {};
}
sub print_pods {
my $self = shift;
$self->print_pod(sort keys %{$self->pod_info});
}
sub print_pod {
my $self = shift;
my @args = @_ ? @_ : @ARGV;
my $pods = $self->pod_info;
while (@args) {
(my $pod = lc(shift @args)) =~ s/\.pod$//;
if ( exists $pods->{$pod} ) {
print "\t'$pod' translated from Perl $pods->{$pod}\n";
}
else {
print "\t'$pod' doesn't yet exists\n";
}
}
}
1;
POD2-Base-0.043/lib/POD2/Base.pod 0000644 0000000 0000000 00000015507 11526426444 0015742 0 ustar 00root root 0000000 0000000
=head1 NAME
POD2::Base - Base module for translations of Perl documentation
=head1 SYNOPSIS
use POD2::Base;
$pod2 = POD2::Base->new({ lang => 'EO' });
@dirs = $pod2->pod_dirs;
$re = $pod2->search_perlfunc_re;
=head1 DESCRIPTION
This module is an abstraction of the code in POD2::IT
and POD2::FR. These modules belong to the Italian and
the French translation projects of core Perl pods.
Once a translation package had been installed, the translated
documentation can be accessed with:
$ perldoc POD2::<lang>::<podname>
(where <lang> is a language abbreviation like IT, FR,
TLH, etc.)
This is guaranteed to work even for older versions of
L<perldoc|perldoc>. It is not very convenient but always works.
To improve the support to read translated docs, the
L<perldoc|perldoc> utility (since version 3.14_01) was updated
to find translated PODs via:
$ perldoc -L IT <podpage>
$ perldoc -L FR -f <function>
$ perldoc -L TH -q <FAQregex>
(I<Note>: this support was shipped together with the
recently released 5.10.0 version the Perl interpreter.)
The objective of this class is to provide a minimum
base to help C<perldoc> and authors of translation
packages to do their job.
=head1 SUBCLASSING
If you want to write a translation package (and have
some customization needs), your
work may be diminished if you subclass C<Pod::Base>.
For example, a minimum example is provided below:
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re { # makes 'perldoc -f' work
return 'Klingon Listing of Perl Functions';
}
1;
And then
$ perldoc -L tlh perlintro
will present you the introduction of Perl in Klingon language
(provided a F<POD2/TLH/perlintro.pod> file was shipped together
with F<POD2/TLH.pm>) and
$ perldoc -L tlh -f pack
will find you the Klingon documentation of C<pack> (if
F<POD2/TLH/perlfunc.pod> was made available as well).
=head1 METHODS
This module has been made into a proper class
with a very small API.
=over 4
=item B<new>
$pod2 = POD2::Base->new(\%args);
$pod2 = POD2::ANY->new();
The constructor. An actual call might look like this:
$pod2 = POD2::Base->new({ lang => 'tlh' });
where the supported options are:
=over 4
=item * "lang"
Specifies the language code we're interested in.
This is required, but can be extracted from
the name of a subclass. Read below.
=item * "inc"
This is used to override the list of Perl
library directories where POD documents
are searched (namely, C<@INC>). Most of the
time, you don't want to mess with that.
It's handy for debugging and testing.
It must be an array ref.
=back
If C<POD2::ANY> is a subclass of C<POD2::Base>, the
inherited constructor will work without arguments
pulling 'ANY' from the package name and using it
as the intented language code.
Note that use of "inc" in the constructor
freezes the list of library dirs searched by the
C<POD2::Base> instance. If this is not used,
the up-to-date C<@INC> is used at each call
of C<pod_dirs> (so that dynamic changes in
the Perl library path are taken into account).
That's what we meant with the
"Most of the time, you don't want to mess with that"
mentioned above.
=item B<pod_dirs>
@dirs = $pod2->pod_dirs;
@dirs = $pod2->pod_dirs(\%options);
Used by C<Pod::Perldoc> to find out where to
look for translated pods.
The C<POD2::Base> default behavior is to find
F<< POD2/<lang>/ >> directories under the
current Perl library directories (C<@INC>) or
the list given as argument "inc" in the constructor.
The supported options are:
=over 4
=item * "test"
By default, the return of C<pod_dirs> do not
include POD directories which do not exist (tested
with C<-d>). If an explicit false value for this option (like
C<< test => 0 >>) is given, such test is not done
and C<pod_dirs> includes all possible candidates
F<< POD2/<lang>/ >> under the library directories.
(Handy for debugging this module. Not much practical
use for anything else.)
=back
=item B<search_perlfunc_re>
$re = $pod2->search_perlfunc_re;
To implement C<< perldoc -f <function> >>
the current code of C<Pod::Perldoc> uses a hard coded string
"Alphabetical Listing of Perl Functions" or the return
of this method (in a regexp) to skip the introduction
and reach the listing of core functions.
Thus a translation package with a corresponding translated
F<perlfunc.pod> should define this method to
make C<< perldoc -L <lang> -f <function> >>
work properly.
=back
There are other methods documented below. However,
they will probably be superseded in future versions
when more general methods to find and display metadata
on translated PODs are designed and implemented.
=over 4
=item B<pod_info>
$hashref = $pod2->pod_info;
Used by C<POD2::Base> itself. The return contains
some metadata on the translated PODs which is used
by the methods C<print_pod> and C<print_pods>.
When subclassing, you B<should> override this
with the current information on what POD
translations the current package is providing.
=item B<print_pods>
$pod2->print_pods;
Prints all translated pods and the corresponding Perl version
of the original files.
=item B<print_pod>
$pod2->print_pod(@pages);
$pod2->print_pod(); # uses @ARGV
Prints the corresponding Perl version of the original files
corresponding to the pods passed as arguments.
=back
=head1 EXAMPLES
=head2 POD2::TLH
A slightly extended version of C<POD2::TLH>
goes like this:
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re {
return 'Klingon Listing of Perl Functions';
}
sub pod_info {
return { perlintro => '5.8.8' };
}
1;
And you may try:
use POD2::TLH;
my $pod2 = 'POD2::TLH';
$pod2->print_pods();
$pod2->print_pod('pod_foo', 'pod_baz', ...);
=head2 THE INSTALLED FILES
If you want to find out which language-specific
POD files are installed at your Perl,
you could use a code similar to this.
use File::Find;
use POD2::Base;
my $pod2 = POD2::Base->new({ lang => $lang });
my @files;
find sub { push @files, $File::Find::name } if -f },
$pod2->pod_dirs;
print "$_\n" for @files;
In the C<POD2-Base> distribution tarball, a script
F<eg/list.pl> is included with an improved
version of this code.
The rules of finding POD in F<.pod>, F<.pm> files and others
belong to L<Pod::Perldoc>. So C<POD2::Base> do not try
to repeat them here.
=head1 AUTHORS
Enrico Sorcinelli E<lt>bepi at perl.itE<gt> (the original POD2::IT code)
Adriano Ferreira E<lt>ferreira at cpan.orgE<gt>
=head1 SEE ALSO
L<POD2::IT>, L<POD2::FR>, L<POD2::LT>, L<POD2::CN>, L<perldoc>, L<perl>.
=head1 COPYRIGHT AND LICENCE
Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=cut
POD2-Base-0.043/lib/POD2/PT/ 0000755 0000000 0000000 00000000000 11526426444 0014677 5 ustar 00root root 0000000 0000000 POD2-Base-0.043/lib/POD2/PT/POD2/ 0000755 0000000 0000000 00000000000 11526426444 0015403 5 ustar 00root root 0000000 0000000 POD2-Base-0.043/lib/POD2/PT/POD2/Base.pod 0000644 0000000 0000000 00000020017 11526426444 0016761 0 ustar 00root root 0000000 0000000
=encoding utf8
=head1 NAME/NOME
POD2::Base~[pt] - Módulo básico para traduções de documentação Perl
=head1 SINOPSE
use POD2::Base;
$pod2 = POD2::Base->new({ lang => 'EO' });
@dirs = $pod2->pod_dirs;
$re = $pod2->search_perlfunc_re;
=head1 DESCRIÇÃO
Este código é uma abstração do código em POD2::IT e
POD2::FR, módulos que pertencem aos projetos
italiano e francês de tradução dos documentos
que acompanham o interpretador Perl.
Com o pacote de tradução já instalado, a documentação
traduzida pode ser acessada através do comando:
$ perldoc POD2::<lang>::<podname>
(onde <lang> é uma abreviação para linguagem como
IT, FR, TLH, etc.)
Isto funciona seguramente até para as versões antigas
do L<perldoc>. Não é muito conveniente mas sempre funciona.
Para incrementar o suporte para leitura destes documentos
traduzidos, o programa L<perldoc> (desde a versão 3.14_01)
foi atualizado para encontrar PODs traduzidos assim:
$ perldoc -L IT <podpage>
$ perldoc -L FR -f <function>
$ perldoc -L TLH -q <FAQregex>
(Nota: Este suporte foi distribuÃdo junto da versão
5.10.0 do interpretador Perl recentemente disponilizado
no CPAN.)
O objetivo desta classe é prover uma base mÃnima para
ajudar o C<perldoc> e os autores de projetos de tradução
a fazerem seu trabalho.
=head1 SUBCLASSES
Se você quer escrever um pacote de tradução (e tem algumas
necessidades de personalização), seu trabalho pode ser
diminuÃdo se você criar uma subclasse de C<POD2::Base>.
Por exemplo, um exemplo mÃnimo é ilustrado abaixo.
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re { # ajuda 'perldoc -f' a funcionar
return 'Klingon Listing of Perl Functions';
}
1;
E então
$ perldoc -L tlh perlintro
vai lhe apresentar a introdução de Perl na linguagem Klingon
(desde que um arquivo F<POD2/TLH/perlintro.pod> tenha sido
distribuÃdo junto com F<POD2/TLH.pm>) e
$ perldoc -L tlh -f pack
vai encontrar a documentação em Klingon de C<pack> (se
F<POD2/TLH/perlfunc.pod> foi disponibilizado também).
=head1 MÉTODOS
Este módulo foi projetado como uma classe OO com uma
API bem pequena.
=over 4
=item B<new>
$pod2 = POD2::Base->new(\%args);
$pod2 = POD2::ANY->new();
O constructor. A criação de uma instância pode se fazer
de modo similar a:
$pod2 = POD2::Base->new({ lang => 'tlh' });
onde as opções suportadas são:
=over 4
=item * "lang"
Especifica o código da linguagem em que estamos interessados.
Este parâmetro é obrigatório, mas pode ser extraÃdo
do nome da subclasse, como explicado mais abaixo.
=item * "inc"
Este parâmetro é usado para substituir a lista
de diretórios para as bibliotecas Perl onde procuram-se
os documentos POD (ou seja, C<@INC>). Na maior parte
do tempo, você não vai querer mexer com isto.
Este parâmetro é mais útil para I<debugging> e testes.
Espera-se um I<array ref>.
=back
Se C<POD2::ANY> é uma subclasse de C<POD2::Base>,
o construtor herdado funcionará sem argumentos
extraindo 'ANY' do nome do pacote e usando-o como
o código da linguagem desejada.
Note que o uso de "inc" no construtor
congela a lista de diretórios vasculhados pela
instância C<POD2::Base>. Se não é usado,
o conteúdo atualizado de C<@INC> é usado em cada
chamada de C<pod_dirs> (de tal forma que mudanças
dinâmicas no I<path> para as bibliotecas Perl
são percebidas). É isto que querÃamos dizer
com "Na maior parte
do tempo, você não vai querer mexer com isto."
=item B<pod_dirs>
@dirs = $pod2->pod_dirs;
@dirs = $pod2->pod_dirs(\%options);
Usado por C<Pod::Perldoc> para descobrir onde
procurar por PODs traduzidos.
O comportamento padrão de C<POD2::Base> é encontrar
cada diretório F<< POD2/<lang>/ >> sob os diretórios
de bibliotecas Perl (C<@INC>) ou na lista
dada como o argumento "inc" no construtor.
As opções suportadas são:
=over 4
=item * "test"
Por I<default>, o retorno de C<pod_dirs> não inclui
diretórios POD que não existem (testados com C<-d>).
Se um valor falso explÃcito é dado para esta
opção (por exemplo, C<< test => 0 >>), este teste
não é feito e C<pod_dirs> inclui todos candidatos
F<< POD2/<lang>/ >> abaixo dos diretórios de bibliotecas.
(Útil para o I<debugging> deste módulo, mas
sem outros usos práticos além deste.)
=back
=item B<search_perlfunc_re>
$re = $pod2->search_perlfunc_re;
Para implementar C<< perldoc -f <function> >>
o código atual de C<Pod::Perldoc> usa um I<string>
fixo "Alphabetical Listing of Perl Functions" ou o
retorno deste método (em uma regex) para pular
a introdução e alcançar a listagem das funções
I<builtin>. Então um pacote de tradução com
a correspondente tradução de F<perlfunc.pod> deve
definir este método para fazer
C<< perldoc -L <lang> -f <function> >>
funcionar corretamente.
=back
Há outros métodos documentados abaixo. Entretanto,
eles provavelmente serão tornados obsoletos em
versões futuras quando forem projetados e
implementados métodos mais gerais de encontrar
e mostrar os metadados sobre os PODs traduzidos.
=over 4
=item B<pod_info>
$hashref = $pod2->pod_info;
Usado pelo próprio C<POD2::Base> e seus ancestrais
C<POD2::IT> e C<POD2::FR>. O retorno contém
alguns metadados sobre os PODs traduzidos usados
pelos métodos C<print_pod> e C<print_pods>.
Ao fazer subclasses seguindo o padrão de C<POD2::IT>
e C<POD2::FR>, você B<deve> redefinir este método
com a informação atual sobre quais traduções
POD o pacote atual está disponibilizando.
=item B<print_pods>
$pod2->print_pods;
Mostra (via C<print>) todos PODs traduzidos e a versão correspondente
de Perl dos arquivos originais.
=item B<print_pod>
$pod2->print_pod(@pages);
$pod2->print_pod(); # usa @ARGV
Mostra a versão de Perl correspondente dos arquivos originais
associados aos PODs passados como argumentos.
=back
=head1 EXEMPLOS
=head2 POD2::TLH
Uma versão mais completa de C<POD2::TLH>
pode-se parecer com isto:
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re {
return 'Klingon Listing of Perl Functions';
}
sub pod_info {
return { perlintro => '5.8.8' };
}
1;
E você pode experimentar:
use POD2::TLH;
my $pod2 = 'POD2::TLH';
$pod2->print_pods();
$pod2->print_pod('pod_foo', 'pod_baz', ...);
=head2 OS ARQUIVOS INSTALADOS
Se você quer descobrir quais arquivos PODs
de uma dada linguagem que estão instalados
junto com seu interpretador Perl, você pode
usar um código similar a este.
use File::Find;
use POD2::Base;
my $pod2 = POD2::Base->new({ lang => $lang });
my @files;
find sub { push @files, $File::Find::name } if -f },
$pod2->pod_dirs;
print "$_\n" for @files;
Na distribuição C<POD2-Base>, é incluÃdo um script
F<eg/list.pl> com uma versão estendida
deste código.
As regras para encontrar POD em arquivos F<.pod>, F<.pm> e
outros pertencem ao módulo L<Pod::Perldoc>. Assim C<POD2::Base>
não tenta repetir esta funcionalidade aqui.
=head1 AUTORES
Enrico Sorcinelli E<lt>bepi at perl.itE<gt> (pelo código original em POD2::IT)
Adriano Ferreira E<lt>ferreira at cpan.orgE<gt>
=head1 VEJA TAMBÉM
L<POD2::IT>, L<POD2::FR>, L<POD2::LT>, L<POD2::CN>, L<perldoc>, L<perl>.
A versão original deste documento: L<POD2::Base>.
(O propósito desta tradução é servir como um primeiro teste
para experimentar o suporte dos vários modules Pod e I<sites> Perl
aos PODs traduzidos.)
(This translation was supplied as a front test against the support
of the many Pod modules and Perl sites on translated PODs.)
=head1 COPYRIGHT E LICENÇA
Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=cut
=begin meta
---
date: 2008-02-25T11:01:45
md5: 47896a7d12987b2f18179eac7f52f8b2
revision: 3
translated_from:
history: []
md5: ~
uri: http://search.cpan.org/src/FERREIRA/POD2-Base-0.04/lib/POD2/Base.pod
=end meta
POD2-Base-0.043/t/ 0000755 0000000 0000000 00000000000 11526426444 0013345 5 ustar 00root root 0000000 0000000 POD2-Base-0.043/t/01_use.t 0000644 0000000 0000000 00000000160 11526426444 0014623 0 ustar 00root root 0000000 0000000
use Test::More tests => 1;
BEGIN { use_ok('POD2::Base') };
diag( "Testing POD2::Base $POD2::Base::VERSION" );
POD2-Base-0.043/t/02_basic.t 0000644 0000000 0000000 00000003220 11526426444 0015111 0 ustar 00root root 0000000 0000000
use strict;
use Test::More tests => 15;
BEGIN { use_ok( 'POD2::Base' ); }
# subsumes_dir( '/usr/lib/perl/POD2/TLH', 'POD2/TLH' ) is true
sub subsumes_dir {
my $dir = shift;
my $tail = shift;
my @dir_segments = File::Spec->splitdir( $_ );
return $tail eq join '/', @dir_segments[-2,-1];
}
{
my $pod2 = POD2::Base->new({ lang => 'tlh' });
isa_ok( $pod2, 'POD2::Base' );
is( $pod2->{lang}, 'TLH', 'the right lang' );
my @dirs = $pod2->pod_dirs({ test => 0 }); # don't test for -d
is( @dirs, @INC, 'pod dirs searched all over @INC' );
my @ok = grep { subsumes_dir( $_, 'POD2/TLH' ) } @dirs;
is( @ok, @INC, 'all pod dirs end with "POD2/TLH"' );
}
{
my $lib_dir = File::Spec->catdir( 'lib' );
my $pod2 = POD2::Base->new({ lang => 'pt', inc => [$lib_dir] });
isa_ok( $pod2, 'POD2::Base' );
is( $pod2->{lang}, 'PT', 'the right lang' );
my @dirs = $pod2->pod_dirs();
is( @dirs, 1, 'found one dir' );
is( $dirs[0], File::Spec->catdir( $lib_dir, 'POD2', 'PT' ), 'at the right place' );
}
package POD2::TLH;
@POD2::TLH::ISA = qw( POD2::Base );
sub search_perlfunc_re {
return 'Klingon Listing of Functions';
}
package main;
{
my $lib_dir = File::Spec->catdir( 't', 'lib' );
my $pod2 = POD2::TLH->new({ inc => [$lib_dir] });
isa_ok( $pod2, 'POD2::TLH' );
isa_ok( $pod2, 'POD2::Base' );
is( $pod2->{lang}, 'TLH', 'the right lang' );
my @dirs = $pod2->pod_dirs({ test => 0 }); # no test for -d
is( @dirs, 1, 'guessed one dir' );
is( $dirs[0], File::Spec->catdir( $lib_dir, 'POD2', 'TLH' ), "at the right place" );
is( $pod2->search_perlfunc_re, 'Klingon Listing of Functions', 'search_perlfunc_re ok' );
}
POD2-Base-0.043/t/98_pod-coverage.t 0000644 0000000 0000000 00000000256 11526426444 0016430 0 ustar 00root root 0000000 0000000 #perl -T
use Test::More;
eval "use Test::Pod::Coverage 1.04";
plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@;
all_pod_coverage_ok();
POD2-Base-0.043/t/99_pod.t 0000644 0000000 0000000 00000000370 11526426444 0014635 0 ustar 00root root 0000000 0000000 #perl -T
use strict;
use Test::More;
eval "use Test::Pod 1.18";
plan skip_all => "Test::Pod 1.18 required for testing POD" if $@;
plan skip_all => "perl < 5.8 doesn't like utf-8 encoded PODs" if $] < 5.008;
all_pod_files_ok(all_pod_files("."));
POD2-Base-0.043/t/lib/ 0000755 0000000 0000000 00000000000 11526426444 0014113 5 ustar 00root root 0000000 0000000 POD2-Base-0.043/t/lib/.exists 0000644 0000000 0000000 00000000000 11526426444 0015421 0 ustar 00root root 0000000 0000000