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.