None
POD2::Base~[pt] - Mo\*'dulo ba\*'sico para traduc\*,o\*~es de documentac\*,a\*~o Perl
use POD2::Base;
$pod2 = POD2::Base->new({ lang => 'EO' });
@dirs = $pod2->pod_dirs;
$re = $pod2->search_perlfunc_re;
Este co\*'digo e\*' uma abstrac\*,a\*~o do co\*'digo em \s-1POD2::IT\s0 e \s-1POD2::FR\s0, mo\*'dulos que pertencem aos projetos italiano e france\*^s de traduc\*,a\*~o dos documentos que acompanham o interpretador Perl.
Com o pacote de traduc\*,a\*~o ja\*' instalado, a documentac\*,a\*~o traduzida pode ser acessada atrave\*'s do comando:
$ perldoc POD2::<lang>::<podname>
(onde <lang> e\*' uma abreviac\*,a\*~o para linguagem como \s-1IT\s0, \s-1FR\s0, \s-1TLH\s0, 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 distribui\*'do junto da versa\*~o 5.10.0 do interpretador Perl recentemente disponilizado no \s-1CPAN\s0.)
O objetivo desta classe e\*' prover uma base mi\*'nima para ajudar o \*(C`perldoc\*(C' e os autores de projetos de traduc\*,a\*~o a fazerem seu trabalho.
Se voce\*^ quer escrever um pacote de traduc\*,a\*~o (e tem algumas necessidades de personalizac\*,a\*~o), seu trabalho pode ser diminui\*'do se voce\*^ criar uma subclasse de \*(C`POD2::Base\*(C'.
Por exemplo, um exemplo mi\*'nimo 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 introduc\*,a\*~o de Perl na linguagem Klingon (desde que um arquivo POD2/TLH/perlintro.pod tenha sido distribui\*'do junto com \s-1POD2/TLH\s0.pm) e
$ perldoc -L tlh -f pack
vai encontrar a documentac\*,a\*~o em Klingon de \*(C`pack\*(C' (se POD2/TLH/perlfunc.pod foi disponibilizado tambe\*'m).
Este mo\*'dulo foi projetado como uma classe \s-1OO\s0 com uma \s-1API\s0 bem pequena.
$pod2 = POD2::Base->new(\%args); $pod2 = POD2::ANY->new(); O constructor. A criac\*,a\*~o de uma insta\*^ncia pode se fazer de modo similar a: $pod2 = POD2::Base->new({ lang => 'tlh' }); onde as opc\*,o\*~es suportadas sa\*~o:
\*(L"lang\*(R" Especifica o co\*'digo da linguagem em que estamos interessados. Este para\*^metro e\*' obrigato\*'rio, mas pode ser extrai\*'do do nome da subclasse, como explicado mais abaixo.
\*(L"inc\*(R" Este para\*^metro e\*' usado para substituir a lista de direto\*'rios para as bibliotecas Perl onde procuram-se os documentos \s-1POD\s0 (ou seja, @INC). Na maior parte do tempo, voce\*^ na\*~o vai querer mexer com isto. Este para\*^metro e\*' mais u\*'til para debugging e testes. Espera-se um array ref.
Se \*(C`POD2::ANY\*(C' e\*' uma subclasse de \*(C`POD2::Base\*(C', o construtor herdado funcionara\*' sem argumentos extraindo '\s-1ANY\s0' do nome do pacote e usando-o como o co\*'digo da linguagem desejada. Note que o uso de \*(L"inc\*(R" no construtor congela a lista de direto\*'rios vasculhados pela insta\*^ncia \*(C`POD2::Base\*(C'. Se na\*~o e\*' usado, o conteu\*'do atualizado de @INC e\*' usado em cada chamada de \*(C`pod_dirs\*(C' (de tal forma que mudanc\*,as dina\*^micas no path para as bibliotecas Perl sa\*~o percebidas). E\*' isto que queri\*'amos dizer com \*(L"Na maior parte do tempo, voce\*^ na\*~o vai querer mexer com isto.\*(R"
@dirs = $pod2->pod_dirs; @dirs = $pod2->pod_dirs(\%options); Usado por \*(C`Pod::Perldoc\*(C' para descobrir onde procurar por PODs traduzidos. O comportamento padra\*~o de \*(C`POD2::Base\*(C' e\*' encontrar cada direto\*'rio POD2/<lang>/ sob os direto\*'rios de bibliotecas Perl (@INC) ou na lista dada como o argumento \*(L"inc\*(R" no construtor. As opc\*,o\*~es suportadas sa\*~o:
\*(L"test\*(R" Por default, o retorno de \*(C`pod_dirs\*(C' na\*~o inclui direto\*'rios \s-1POD\s0 que na\*~o existem (testados com \*(C`-d\*(C'). Se um valor falso expli\*'cito e\*' dado para esta opc\*,a\*~o (por exemplo, \*(C`test => 0\*(C'), este teste na\*~o e\*' feito e \*(C`pod_dirs\*(C' inclui todos candidatos POD2/<lang>/ abaixo dos direto\*'rios de bibliotecas. (U\*'til para o debugging deste mo\*'dulo, mas sem outros usos pra\*'ticos ale\*'m deste.)
$re = $pod2->search_perlfunc_re; Para implementar \*(C`perldoc -f <function>\*(C' o co\*'digo atual de \*(C`Pod::Perldoc\*(C' usa um string fixo \*(L"Alphabetical Listing of Perl Functions\*(R" ou o retorno deste me\*'todo (em uma regex) para pular a introduc\*,a\*~o e alcanc\*,ar a listagem das func\*,o\*~es builtin. Enta\*~o um pacote de traduc\*,a\*~o com a correspondente traduc\*,a\*~o de perlfunc.pod deve definir este me\*'todo para fazer \*(C`perldoc -L <lang> -f <function>\*(C' funcionar corretamente.
Ha\*' outros me\*'todos documentados abaixo. Entretanto, eles provavelmente sera\*~o tornados obsoletos em verso\*~es futuras quando forem projetados e implementados me\*'todos mais gerais de encontrar e mostrar os metadados sobre os PODs traduzidos.
$hashref = $pod2->pod_info; Usado pelo pro\*'prio \*(C`POD2::Base\*(C' e seus ancestrais \*(C`POD2::IT\*(C' e \*(C`POD2::FR\*(C'. O retorno conte\*'m alguns metadados sobre os PODs traduzidos usados pelos me\*'todos \*(C`print_pod\*(C' e \*(C`print_pods\*(C'. Ao fazer subclasses seguindo o padra\*~o de \*(C`POD2::IT\*(C' e \*(C`POD2::FR\*(C', voce\*^ deve redefinir este me\*'todo com a informac\*,a\*~o atual sobre quais traduc\*,o\*~es \s-1POD\s0 o pacote atual esta\*' disponibilizando.
$pod2->print_pods; Mostra (via \*(C`print\*(C') todos PODs traduzidos e a versa\*~o correspondente de Perl dos arquivos originais.
$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.
Uma versa\*~o mais completa de \*(C`POD2::TLH\*(C' 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', ...);
Se voce\*^ quer descobrir quais arquivos PODs de uma dada linguagem que esta\*~o instalados junto com seu interpretador Perl, voce\*^ pode usar um co\*'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 distribuic\*,a\*~o \*(C`POD2-Base\*(C', e\*' inclui\*'do um script eg/list.pl com uma versa\*~o estendida deste co\*'digo.
As regras para encontrar \s-1POD\s0 em arquivos .pod, .pm e outros pertencem ao mo\*'dulo Pod::Perldoc. Assim \*(C`POD2::Base\*(C' na\*~o tenta repetir esta funcionalidade aqui.
Enrico Sorcinelli <bepi at perl.it> (pelo co\*'digo original em \s-1POD2::IT\s0)
Adriano Ferreira <ferreira at cpan.org>
\s-1POD2::IT\s0, \s-1POD2::FR\s0, \s-1POD2::LT\s0, \s-1POD2::CN\s0, perldoc, perl.
A versa\*~o original deste documento: POD2::Base.
(O propo\*'sito desta traduc\*,a\*~o e\*' servir como um primeiro teste para experimentar o suporte dos va\*'rios 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 (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.