The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
POD2-Base-0.043
River stage one • 3 direct dependents • 3 total dependents
5 ++
/ lib/POD2/PT/POD2/Base.pod

NAME/NOME

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

SINOPSE

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

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

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

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 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).

MÉTODOS

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.

    $pod2->print_pods;

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

    $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.

EXEMPLOS

POD2::TLH

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', ...);

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

AUTORES

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

Adriano Ferreira <ferreira at cpan.org>

VEJA TAMBÉM

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