POD2::PT::POD2::Base(3User Contributed Perl DocumentatiPOD2::PT::POD2::Base(3)NAME/NOME
POD2::Base~[pt] - Modulo basico para traduco~es de documentaca~o Perl
SINOPSE
use POD2::Base;
$pod2 = POD2::Base->new({ lang => 'EO' });
@dirs = $pod2->pod_dirs;
$re = $pod2->search_perlfunc_re;
DESCRICA~O
Este codigo e uma abstraca~o do codigo em POD2::IT e POD2::FR, modulos
que pertencem aos projetos italiano e frances de traduca~o dos
documentos que acompanham o interpretador Perl.
Com o pacote de traduca~o ja instalado, a documentaca~o traduzida pode
ser acessada atraves do comando:
$ perldoc POD2::<lang>::<podname>
(onde <lang> e uma abreviaca~o para linguagem como IT, FR, TLH, etc.)
Isto funciona seguramente ate para as verso~es antigas do perldoc. Na~o
e muito conveniente mas sempre funciona.
Para incrementar o suporte para leitura destes documentos traduzidos, o
programa perldoc (desde a versa~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 distribuido junto da versa~o 5.10.0 do
interpretador Perl recentemente disponilizado no CPAN.)
O objetivo desta classe e prover uma base minima para ajudar o
"perldoc" e os autores de projetos de traduca~o a fazerem seu trabalho.
SUBCLASSES
Se voce quer escrever um pacote de traduca~o (e tem algumas
necessidades de personalizaca~o), seu trabalho pode ser diminuido se
voce criar uma subclasse de "POD2::Base".
Por exemplo, um exemplo minimo e 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 enta~o
$ perldoc -L tlh perlintro
vai lhe apresentar a introduca~o de Perl na linguagem Klingon (desde
que um arquivo POD2/TLH/perlintro.pod tenha sido distribuido junto com
POD2/TLH.pm) e
$ perldoc -L tlh -f pack
vai encontrar a documentaca~o em Klingon de "pack" (se
POD2/TLH/perlfunc.pod foi disponibilizado tambem).
METODOS
Este modulo foi projetado como uma classe OO com uma API bem pequena.
new
$pod2 = POD2::Base->new(\%args);
$pod2 = POD2::ANY->new();
O constructor. A criaca~o de uma instancia pode se fazer de modo
similar a:
$pod2 = POD2::Base->new({ lang => 'tlh' });
onde as opco~es suportadas sa~o:
· "lang"
Especifica o codigo da linguagem em que estamos interessados.
Este parametro e obrigatorio, mas pode ser extraido do nome da
subclasse, como explicado mais abaixo.
· "inc"
Este parametro e usado para substituir a lista de diretorios
para as bibliotecas Perl onde procuram-se os documentos POD (ou
seja, @INC). Na maior parte do tempo, voce na~o vai querer
mexer com isto. Este parametro e mais util para debugging e
testes.
Espera-se um array ref.
Se "POD2::ANY" e uma subclasse de "POD2::Base", o construtor
herdado funcionara sem argumentos extraindo 'ANY' do nome do pacote
e usando-o como o codigo da linguagem desejada.
Note que o uso de "inc" no construtor congela a lista de diretorios
vasculhados pela instancia "POD2::Base". Se na~o e usado, o
conteudo atualizado de @INC e usado em cada chamada de "pod_dirs"
(de tal forma que mudancas dinamicas no path para as bibliotecas
Perl sa~o percebidas). E isto que queriamos dizer com "Na maior
parte do tempo, voce na~o vai querer mexer com isto."
pod_dirs
@dirs = $pod2->pod_dirs;
@dirs = $pod2->pod_dirs(\%options);
Usado por "Pod::Perldoc" para descobrir onde procurar por PODs
traduzidos.
O comportamento padra~o de "POD2::Base" e encontrar cada diretorio
POD2/<lang>/ sob os diretorios de bibliotecas Perl (@INC) ou na
lista dada como o argumento "inc" no construtor.
As opco~es suportadas sa~o:
· "test"
Por default, o retorno de "pod_dirs" na~o inclui diretorios POD
que na~o existem (testados com "-d"). Se um valor falso
explicito e dado para esta opca~o (por exemplo, "test => 0"),
este teste na~o e feito e "pod_dirs" inclui todos candidatos
POD2/<lang>/ abaixo dos diretorios de bibliotecas. (Util para
o debugging deste modulo, mas sem outros usos praticos alem
deste.)
search_perlfunc_re
$re = $pod2->search_perlfunc_re;
Para implementar "perldoc -f <function>" o codigo atual de
"Pod::Perldoc" usa um string fixo "Alphabetical Listing of Perl
Functions" ou o retorno deste metodo (em uma regex) para pular a
introduca~o e alcancar a listagem das funco~es builtin. Enta~o um
pacote de traduca~o com a correspondente traduca~o de perlfunc.pod
deve definir este metodo para fazer "perldoc -L <lang> -f
<function>" funcionar corretamente.
Ha outros metodos documentados abaixo. Entretanto, eles provavelmente
sera~o tornados obsoletos em verso~es futuras quando forem projetados e
implementados metodos mais gerais de encontrar e mostrar os metadados
sobre os PODs traduzidos.
pod_info
$hashref = $pod2->pod_info;
Usado pelo proprio "POD2::Base" e seus ancestrais "POD2::IT" e
"POD2::FR". O retorno contem alguns metadados sobre os PODs
traduzidos usados pelos metodos "print_pod" e "print_pods".
Ao fazer subclasses seguindo o padra~o de "POD2::IT" e "POD2::FR",
voce deve redefinir este metodo com a informaca~o atual sobre quais
traduco~es POD o pacote atual esta disponibilizando.
print_pods
$pod2->print_pods;
Mostra (via "print") todos PODs traduzidos e a versa~o
correspondente de Perl dos arquivos originais.
print_pod
$pod2->print_pod(@pages);
$pod2->print_pod(); # usa @ARGV
Mostra a versa~o de Perl correspondente dos arquivos originais
associados aos PODs passados como argumentos.
EXEMPLOS
POD2::TLH
Uma versa~o mais completa de "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 voce pode experimentar:
use POD2::TLH;
my $pod2 = 'POD2::TLH';
$pod2->print_pods();
$pod2->print_pod('pod_foo', 'pod_baz', ...);
OS ARQUIVOS INSTALADOS
Se voce quer descobrir quais arquivos PODs de uma dada linguagem que
esta~o instalados junto com seu interpretador Perl, voce pode usar um
codigo 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 distribuica~o "POD2-Base", e incluido um script eg/list.pl com uma
versa~o estendida deste codigo.
As regras para encontrar POD em arquivos .pod, .pm e outros pertencem
ao modulo Pod::Perldoc. Assim "POD2::Base" na~o tenta repetir esta
funcionalidade aqui.
AUTORES
Enrico Sorcinelli <bepi at perl.it> (pelo codigo original em POD2::IT)
Adriano Ferreira <ferreira at cpan.org>
VEJA TAMBEM
POD2::IT, POD2::FR, POD2::LT, POD2::CN, perldoc, perl.
A versa~o original deste documento: POD2::Base.
(O proposito desta traduca~o e servir como um primeiro teste para
experimentar o suporte dos varios modules Pod e 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.)
COPYRIGHT E LICENCA
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.
perl v5.14.1 2008-02-25 POD2::PT::POD2::Base(3)
