GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
POD2::PT::POD2::Base(3) User Contributed Perl Documentation POD2::PT::POD2::Base(3)

POD2::Base~[pt] - Módulo básico para traduções de documentação Perl

    use POD2::Base;
    $pod2 = POD2::Base->new({ lang => 'EO' });

    @dirs = $pod2->pod_dirs;
    $re = $pod2->search_perlfunc_re;

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 perldoc. Não é muito conveniente mas sempre funciona.

Para incrementar o suporte para leitura destes documentos traduzidos, o programa 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 "perldoc" e os autores de projetos de tradução a fazerem seu trabalho.

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 "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 POD2/TLH/perlintro.pod tenha sido distribuído junto com POD2/TLH.pm) e

    $ perldoc -L tlh -f pack

vai encontrar a documentação em Klingon de "pack" (se POD2/TLH/perlfunc.pod foi disponibilizado também).

Este módulo foi projetado como uma classe OO com uma API bem pequena.
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:

  • "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.

  • "inc"

    Este parâmetro é usado para substituir a lista de diretórios para as bibliotecas Perl onde procuram-se os documentos POD (ou seja, @INC). Na maior parte do tempo, você não vai querer mexer com isto. Este parâmetro é mais útil para debugging e testes.

    Espera-se um array ref.

Se "POD2::ANY" é uma subclasse de "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 "POD2::Base". Se não é usado, o conteúdo atualizado de @INC é usado em cada chamada de "pod_dirs" (de tal forma que mudanças dinâmicas no 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."

pod_dirs
    @dirs = $pod2->pod_dirs;
    @dirs = $pod2->pod_dirs(\%options);
    

Usado por "Pod::Perldoc" para descobrir onde procurar por PODs traduzidos.

O comportamento padrão de "POD2::Base" é encontrar cada diretório POD2/<lang>/ sob os diretórios de bibliotecas Perl (@INC) ou na lista dada como o argumento "inc" no construtor.

As opções suportadas são:

"test"

Por default, o retorno de "pod_dirs" não inclui diretórios POD que não existem (testados com "-d"). Se um valor falso explícito é dado para esta opção (por exemplo, "test => 0"), este teste não é feito e "pod_dirs" inclui todos candidatos POD2/<lang>/ abaixo dos diretórios de bibliotecas. (Útil para o debugging deste módulo, mas sem outros usos práticos além deste.)

search_perlfunc_re
    $re = $pod2->search_perlfunc_re;
    

Para implementar "perldoc -f <function>" o código atual de "Pod::Perldoc" usa um 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 builtin. Então um pacote de tradução com a correspondente tradução de perlfunc.pod deve definir este método para fazer "perldoc -L <lang> -f <function>" funcionar corretamente.

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.

pod_info
    $hashref = $pod2->pod_info;
    

Usado pelo próprio "POD2::Base" e seus ancestrais "POD2::IT" e "POD2::FR". O retorno contém alguns metadados sobre os PODs traduzidos usados pelos métodos "print_pod" e "print_pods".

Ao fazer subclasses seguindo o padrão de "POD2::IT" e "POD2::FR", você deve redefinir este método com a informação atual sobre quais traduções POD o pacote atual está disponibilizando.

print_pods
    $pod2->print_pods;
    

Mostra (via "print") todos PODs traduzidos e a versão correspondente de Perl dos arquivos originais.

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.

Uma versã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 você pode experimentar:

    use POD2::TLH;
    my $pod2 = 'POD2::TLH';
    $pod2->print_pods();
    $pod2->print_pod('pod_foo', 'pod_baz', ...);

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 "POD2-Base", é incluído um script eg/list.pl com uma versão estendida deste código.

As regras para encontrar POD em arquivos .pod, .pm e outros pertencem ao módulo Pod::Perldoc. Assim "POD2::Base" não tenta repetir esta funcionalidade aqui.

Enrico Sorcinelli <bepi at perl.it> (pelo código original em POD2::IT)

Adriano Ferreira <ferreira at cpan.org>

POD2::IT, POD2::FR, POD2::LT, POD2::CN, perldoc, perl.

A versão original deste documento: POD2::Base.

(O propósito desta tradução é servir como um primeiro teste para experimentar o suporte dos vá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.

2008-02-25 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.