r2 - 13 Mar 2006 - GabrielVieira

VEJA TAMBÉM
AUTOR
TRADUZINDO

Observação

Este documento está em formato POD. Para ler este documento, use um formatador de POD, como ``perldoc perlpod''.

NOME

perlpod - the Plain Old Documentation format

DESCRIÇÃO

POD é uma linguagem de marcação simples utilizada por escrever documentação para Perl, programas Perl, e módulos Perl. Tradutores estão disponíveis para converter POD para vários formatos como texto, HTML, man pages, e mais. Marcação de POD consiste em três tipos básicos de parágrafos: ordinário, literal, e comando.

Parágrafo ordinário

A maioria dos parágrafos em sua documentação serão blocos ordinários de texto, como este aqui. Você pode simplesmente digitar o seu texto sem qualquer marcação, utilizando apenas uma linha em branco entre os parágrafos para a separação. Quando formatado, a formatação será mínima, provavelmente com fonte que respeita a proporcionalidade do espaçamento, e talvez até mesmo justificado. Você pode usar codificação de formatação nos parágrafos ordinários, para tipo negrito, itálico, código-estilo, hiperlink , e mais. Tais códigos são explicados na seção ``formatando código'', abaixo.

Parágrafo literal

Parágrafo literal são normalmente usados para apresentar um bloco de código (``codeblock'') ou outro texto que não requer qualquer formatação especial. Um parágrafo literal é diferente dos demais parágrafos por ter seus primeiros caracteres como espaço ou caracter de tabulação (``'tab'''). (Geralmente, todas as linhas do parágrafo começam com espaços e/ou 'tab'.) O texto será reproduzido exatamente como escrito, assumindo a formatação do caractere 'tab' com 8 espaços. Não há suporte a nenhum código de formatação especial, assim você não pode grifar ou qualquer outro tipo de formatação. Um '\' significa '\', e nada mais.

Parágrafo de comando

Um parágrafo de comando é usado para tratamento especial de partes grandes de texto, normalmente como títulos ou partes de listas. O parágrafo de comando é iníciado com ``='' (normalmente todo conteúdo está apenas em uma linha), seguida por um identificador, seguido de um texto arbitrário que será utilizado pelo comando. Os comandos atualmente reconhecidos são :

    =pod

    =head1 Texto do Título

    =head2 Texto do Título

    =head3 Texto do Título

    =head4 Texto do Título

    =over marcador

    =item ítem

    =back

    =begin formato

    =end formato

    =for texto para formatar...

    =encoding tipo de codificador

    =cut

Explicando-os em detalhes:

=head1 Texto de Título

=head2 Texto de Título

=head3 Texto de Título

=head4 Texto de Título

Head1 até head4 produzem títulos, head1 que é o mais alto

nível. O texto no resto deste parágrafo é o conteúdo do

cabeçalho. Por exemplo:

  =head2 Atributos de Objeto

O texto do ``Atributos de Objeto'' é parte do título acima. (Note que

head3 e head4 são adições recentes, não é contemplado por tradutores POD antigos.)

O texto nestes comandos de título pode usar códigos formatação, como demonstrado aqui:

  =head2 Possíveis Valores para C<$/>

Tais comandos são explicados dentro da seção

``formatando códigos '', abaixo.

=over marcador

=item Texto...

=back

Item, over, e back necessita uma explicação mais detalhada: o ``=over'' inicia

o bloco onde será especificado a lista de ítens utilizando o comando ``=item'', ou como

marcador de parágrafo ( ou um groupo de). Ao término de sua lista,

use ``=back'' para terminar o bloco.

O marcador utiliza a opção ``=over'' para indicar a distância de deslocamento, geralmente em 'emes'

(onde cada 'eme' é a largura de um ``M'' na fonte utilizado no documento), ou unidades semelhantes; se não

existir nenhuma opção de marcador, será utilizado o padrão de quatro. (E alguns formatadores podem

simplesmente ignorar qualquer marcador que você prover.) Na descrição do item no

=item descrição do item, você pode utilizar codigos de formatação, como demonstrado abaixo :

  =item Utilizando C<$|> para controlar utilização de memória intermediária

Tais comandos são explicados dentro da seção

``formatando códigos '', abaixo.

Observe também que existe algumas regras básicas para utilizar o bloco ``=over''...

``=back'' :

=cut

Termina um bloco de POD, utilize-o num linha em branco,

simplestemente escrevendo o comando ``=cut'', seguido de outra linha em branco.

Isto fará que o Perl (e o formatado de POD) saiba que as linhas que segue são códigos de Perl.

(A linha em branco antes do ``=cut''

não é tecnicamente necessário, mais antivos processadores de POD requerem isto.)

=pod

O comando ``=pod'' não faz muito coisa por si só, mas ele

informa ao Perl (e aos formatadores de POD) que um bloco de POD inicia aqui. Um

bloco de POD inicia qualquer comando de parágrafo, sendo assim um comando ``=pod'' é

normalmente utilizado quando você quer iniciar um bloco de POD para um

parágrafo ordinário ou parágrafo literal. Por exemplo:

  =item artigo()

  Esta é a função artigo.

  =cut

  sub artigo {

...

  =pod

  Não esqueça de conferir o valor retornado, como em:

    artigo () || die "Não foi possível executar artigo !";

  =cut

=begin nome_do_formato

=end nome_do_formato

=for nome_do_formato texto...

Os comandos ``=for'', ``=begin'' e ``=end'' criará um bloco de texto/código/dados que

não é interpretado como um texto de POD normal, mas será passado

diretamente para formatadores especiais. O formatador que compreender o formato

utilizado neste bloco o utilizará, caso contrário este bloco

será completamente ignorado.

Um comando ``=begin nome_do_formato'', alguns parágrafos, e um

comando ``=end nome_do_formato'', signifique que o texto/dados no bloco

é direcionado para os formatadores que comprrendem o formato especial

chamado nome_do_formato. Por exemplo,

  =begin html

  <hr><img src="thang.png">

  <p> Este é um parágrafo de HTML puro</p>

  =end html

O comando ``=for nome_do_formato texto...''

especifica isto é apenas um parágrafo (iniciando

logo após nome_do_formato) neste formato especial.

  =for htmL<hr><img src= "thang.png">

  <p> Este é um parágrafo de HTML puro</p>

Isto significa a mesma coisa que o bloco anterior ``=begin html''... ``=end html''.

Quer dizer, com ``=for'', você pode ter o apenas um parágrafo

de texto (i.e., o texto em ``=for nome_do_formato texto...''), mas com

``=begin nome_do_formato'' ... ``=end nome_do_formato'', você pode ter qualquer quantidade

de linhas no bloco. (Note que ainda deve haver uma linha em branco

depois do comando ``=begin'' e uma linha em branco antes o ``=end''

comando.

Aqui são alguns exemplos de como usar estes comandos :

  =begin html

  <br>Figura 1.<br><IMG SRC="figure1.png"><br>

  =end html

  =begin texto

    ---------------

    |  foo         |

    |        barra |

    ---------------

  ^^^^ Figure 1. ^^^^

  =end texto

Alguns nomes de formatos atualmente conhecidos pelo formadores incluem

``roff'', ``man'', ``latex'', ``tex'', ``text'', e ``html.'' (Alguns

formatadores tratarão alguns destes como sinônimos.)

O nome de formato de ``comment'' é utilizado apenas para a criação de notas (presumivelmente

para você) e isso não aparecerá em qualquer versão formatada de um documento POD:

  =for comment

  Tenha certeza que todas as opções disponíveis estão documentadas!

Alguns nome_do_formato requererá um cólon principal (como em

"=for :nome_do_formato", ou

"=begin :nome_do_formato" ... "=end:nome_do_formato"),

para informar que text não é algum tipo de dados, mas na veradade é texto de POD

(i.e., contendo formatação possivelmente codifica) isso simplesmente não é para ser

formatado normalmente (por exemplo, talvez não seja um parágrafo de uso normal, mas poder

ser formatado como uma nota de rodapé).

=encoding codificador_tipo

Este comando é usado para declarar a tipo de codificação de um documento. A maioria

dos usuários não precisarão disto; mas se sua codificação não é o US-ASCII ou Latino-1,

então insira o comando =encoding codificador_tipo no documento para indicar ao

formatador POD como decodifica-lo.

Para codificador_tipo, utilize um nome reconhecido pelo módulo the Encode::Supported manpage. Exemplos:

  =encoding utf8

  =encoding koi8-r

  =encoding ShiftJIS

  =encoding big5

E não esqueça, ao usar qualquer comando, o comando dura até o término de seu parágrafo, não sua linha. Assim no exemplos abaixo, você pode ver que todo comando precisa do espaço em branco depois dele, para terminar seu parágrafo. Alguns exemplos de listas incluem:

  =over

  =item *

  Primeiro item

  =item *

  Segundo item

  =back

  =over

  =item Foo()

  Descrição da função Foo

  =item Bar()

  Descrição da função Bar

  =back

Códigos de formatação

Em parágrafos ordinários e em alguns parágrafos de comando, vários códigos de formatação (a.k.a. ``seqüências interiores'') pode ser usado:

 "seqüências interiores" são termos desatualizado.

 Prefira "formatação codificada".

I<texto> -- texto itálico: <> >>; Usado para enfatizar (``seja I<cuidadoso!>'') e para os parâmetros; (``redo I<IDENTIFICADOR>'')
B<texto> -- texto em negrito: <> >>; Usado para argumentos (``perl's B<-n> argumento''), programas; (``alguns sistemas provêem um B<chfn> para isso''), para enfatizar; (``seja B<cuidadoso!>''), e assim por diante; (``e esta característica é conhecida como B<auto-reanimação>'').
C<código> -- texto de código: X << C<>>>; Utiliza uma fonte de máquina de escrever para o código, ou dá alguma outra indicação de que; isto representa texto de programa (``C<gmtime ($^T)>'') ou alguma outra; forma de informatiquês(``C< drwxr-xr-x>'').
L<nome>--um hiperlink: <> >>; Há várias sintaxes, listadas abaixo. Nas sintaxes dadas,; texto, nome, e seção não pode conter os caractere; '/' e' |'; e qualquer'<' ou'> ' deveria ser encontrado.
E<escape<gt> -- caracteres do tipo escape: <> >>; Bem parecido o HTML/XML &foo; ``referências de entidade'':
F<nome de arquivo<gt> -- usado para nome de arquivos: <>>>; Tipicamente exibido em itálicos. Exemplo: ``F<.cshrc>''
S<texto> -- texto contém espaços que não podem ser quebrados: <> >>; Isto significa que as palavras no texto não deveria ser quebrado; para a próxima linha. Exemplo: S<$x ? $y : $Z>.
X<nome do tópico>--uma entrada de índice: <> >>; Isto é ignorado pela maioria do formatadores, mas alguns podem usar isto por construir; índices. Textos com este código de formatação não são apresentado no texto.; Exemplo: X<absolutizing relative URLs<gt>
oZ<> -- um código de formatação nulo (efeito zero): <> >>; Isto é raramente utilizado. É algumas vezes um modo para contornar a utilização do código; E<...>. Por exemplo, em vez de; ``NE<lt>3'' (para ``N<3'') você poderia escrever; ``NZ<><3'' (o ``Z<>'' quebra ``N'' e; o ``<'' assim eles não podem ser considerados; a parte de um (fictício) ``N<...>'' código.

A maio parte do tempo, você precisará de só um único conjunto de parênteses de ângulo para delimite o começo e término de formatar códigos. Porém, às vezes você vai querer pôr um parêntese de ângulo real ( um sinal maior-que,'>') dentro de um código de formatação. Isto é particularmente comum ao usar um código de formatação para destacar um pedaço de código. Como tudo em Perl, há mais que um modo para fazer isto. Um modo é utilizar caracateres escape,usando um E código:

    C<$a E<lt>=E<gt> $b>

Isto produzirá: ``$a <=> $b'' Um mais legível, e talvez modo mais ``claro'' é usar um substituto conjunto de delimiters que não requer um simples``>'' para ser escaped. Com o formadores de POD que é padronizado com perl5.5.660, dublos parênteses de ângulo (``<<'' e``>>'') talvez possa ser utiilzado se, e somente se, houver espaços em branco logo depois do delimitador de abertura e espaço em branco antes do final do delitador!>Por exemplo, faça o seguinte truque:

    C<< $a <=> $B >>

Na realidade, você pode usar tantos ângulo-parênteses repetidos quanto você desejar, desde que seja o mesmo número deles na abertura e fechamento do delimitador, e ter a certeza que espaços em branco segue o último '<' delimitador de abertura, e certeza que espaços em branco segue o primeiro '>' do delimitador final. (Os espaços em braços são ignorados.) Assim o seguindo também trabalhará:

    C <<< $a <=> $b >>>

    C <<<< $a <=> $b    >>>>

E todos eles querem dizer exatamente igual a isto:

    C<$a E<lt>=E<gt> $b>

Como um exemplo adicional, isto significa que se você quisesse pôr estes pedaço de código no estilo em C(código) estilo:

    open (X,">>thing.dat") || die $!;

    $foo->barra();

você pôde escrever assim:

    C<<< open(X, ">>thing.dat") || die $! >>>

    C<< $foo->barra(); >>

que é presumivelmente mais fácil ler que o modo velho:

    C<open(X, "E<gt>E<gt>thing.dat") || die $!>

    C<$foo-E<gt>bar();>

Isto é atualmente reconhecido pelo pod2text (Pod::Text), pod2man (Pod::Man), e qualquer outro pod2xxx ou tradutores de Pod::Xxxx que usam Pod::Parser 1.093 ou mas recente, ou Pod::Tree 1.02 ou mas recente.

O objetivo

O objetivo é a simplicidade de uso, não o poder de expressão. Onde os parágrafos se pareçam com parágrafos (em formato de bloco), de forma que eles se alinhem visualmente, de que forma que eu possa executar o fmt para reformatar-los facilmente (isso é F7 na minha versão do vi, ou Esc Q na minha versão do emacs). Eu queria que o tradutor sempre considerasse o ', o ` e o " em seu estado natural, no modo literal, assim eu puderia copiá-lo no programa que estou trabalhando, deslocar com espaços, e ter-lo funcionando, literalmente. O formato de POD não possue todos os recursos para escrever um livro. POD tem a intenção apenas de ser um formato de fonte comum para nroff, HTML, TeX? , e outras linguagens de marcação, como usado para documentação online. Existem tradutores para pod2text, pod2html, pod2man (isso é para nroff (1) e troff (1)), pod2latex, e pod2fm. Vários outros estão disponíveis em CPAN.

Embute PODs em Módulos de Perl

Você pode embutir documentação de POD em seus módulos e programas Perl. Inicie sua documentação com uma linha vazia, um comando ``= head1'' no inicio, e termina isto com um comando ``=cut'' e uma linha vazia. Perl ignorará o texto POD. Veja quaisquer um dos módulos de biblioteca Perl como exemplos. Se você vai pôr seu POD no final do arquivo, e está usando marcação de corte END ou DATA, tenha certeza de colocar linha vazia antes do primeiro comando de POD.

  __END__

  =head1 NOME

  Time::Local - compute eficazmente o tempo local e GMT

Sem aquela linha vazia antes do ``=head1'', muitos tradutores não vão reconheceu o ``=head1'' como iniciando um bloco de POD.

Dicas para escrever POD

O comando podchecker existe para conferir a sintaxe do POD apresentando os erros e as advertências. Por exemplo, ele verifica por linhas completamente em branco nos blocos POD e por comandos desconhecidos e códigos de formatação. Você pode também submeter seu documento por um ou mais tradutores e revisar o resultado, ou imprimir e revisá-lo. Alguns dos problemas encontrados podem ser problemas nos tradutores, que você pode ou não quer contonar.

Pod::HTML2Pod

Pod::PXML