=for comment
Este documento está em formato POD. Para ler este documento, use um formatador de POD,
como "perldoc perlpod".

=head1 NOME
X<POD> X<plain old documentation>

perlpod - the Plain Old Documentation format

=head1 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:
L<ordinário|/"Parágrafo ordinário">,
L<literal|/"Parágrafo literal">, e 
L<comando|/"Parágrafo de comando">.


=head2 Parágrafo ordinário
X<POD, parágrafo ordinário> X<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 B<tipo negrito>,
I<itálico>, C<código-estilo>, L<hiperlink |perlfaq>, e mais.  Tais
códigos são explicados na seção "L<formatando código|/"Códigos de formatação">", abaixo.


=head2 Parágrafo literal
X<POD, parágrafo literal> X<literal>

Parágrafo literal são normalmente usados para apresentar um bloco de código ("I<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 ("I<'tab'>").  (Geralmente, todas as linhas do parágrafo 
começam com espaços e/ou I<'tab'>.)  O texto será reproduzido exatamente como escrito, assumindo a
formatação do caractere I<'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.


=head2 Parágrafo de comando
X<POD, 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:

=over

=item C<=head1 I<Texto de Título>>
X<=head1> X<=head2> X<=head3> X<=head4>
X<head1> X<head2> X<head3> X<head4>

=item C<=head2 I<Texto de Título>>

=item C<=head3 I<Texto de Título>>

=item C<=head4 I<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 
"L<formatando códigos |/"Códigos de formatação"> ", abaixo.

=item C<=over I<marcador>>
X<=over> X<=item> X<=back> X<over> X<item> X<back>

=item C<=item I<Texto...>>

=item C<=back>

I<Item>, I<over>, e I<back> necessita uma explicação mais detalhada: o B<"=over"> inicia
o bloco onde será especificado a lista de ítens utilizando o comando B<"=item">, ou como  
marcador de parágrafo ( ou um groupo de).  Ao término de sua lista, 
use B<"=back"> para terminar o bloco. 
O I<marcador> utiliza a opção B<"=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 I<marcador>, será utilizado o padrão de quatro. (E alguns formatadores podem 
simplesmente ignorar qualquer I<marcador> que você prover.) Na I<descrição do item> no 
C<=item I<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 
"L<formatando códigos |/"Códigos de formatação"> ", abaixo.


Observe também que existe algumas regras básicas para utilizar o bloco "=over"...
"=back" :

=over

=item *

Não use "=item"s fora do bloco "=over" ... "=back".

=item *

A primeira coisa depois do comando "=over" deverá ser um "=item", a menos que
não exista nenhum outro item no bloco "=over" ... "=back".

=item *

Não utilize comando "=headI<n>" dentro de um bloco "=over" ... "=back".

=item *

E talvez o mais importante, mantenha os itens consistente: ou utilize
"=item * " para todos eles utilizarem marcadores gráficos (geralmente o simbolo de diamante); ou utilize "=item 1.",
"=item 2.", etc., para produzir listas numeradas; ou utilize "=item foo",
"=item bar", etc. -- isto é, coisas que não se parecem nada marcadores gráficos ou
números.

Se você iniciar com marcadores gráficos ou números, permaneça com eles, pois
os formatadores vão utilizar o primeiro tipo de "=item" para decidir como formatar a
lista.

=back

=item C<=cut>
X<=cut> X<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.)

=item C<=pod>
X<=pod> X<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 I<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

=item C<=begin I<nome_do_formato>>
X<=begin> X<=end> X<=for> X<begin> X<end> X<for>

=item C<=end I<nome_do_formato>>

=item C<=for I<nome_do_formato> I<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 I<nome_do_formato>", alguns parágrafos, e um
comando "=end I<nome_do_formato>", signifique que o texto/dados no bloco
é direcionado para os formatadores que comprrendem o formato especial
chamado I<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 I<nome_do_formato> I<texto...>"
especifica isto é apenas um parágrafo (iniciando
logo após I<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 I<"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 I<nome_do_formato> requererá um cólon principal (como em
C<"=for :nome_do_formato">, ou
C<"=begin :nome_do_formato" ... "=end:nome_do_formato">),
para informar que text não é algum tipo de dados, mas na veradade I<é> 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é).

=item C<=encoding I<codificador_tipo>>
X<=encoding> X<encoding>

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 C<=encoding I<codificador_tipo>> no documento para indicar ao 
formatador POD como decodifica-lo.

Para I<codificador_tipo>, utilize um nome reconhecido pelo módulo L<Encode::Supported>.  Exemplos:

  =encoding utf8

  =encoding koi8-r

  =encoding ShiftJIS

  =encoding big5

=back

E não esqueça, ao usar qualquer comando, o comando dura
até o término de seu I<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

=head2 Códigos de formatação
X<POD, formatando código> X<formatando código>
X<POD, seqüência interior> X<seqüência interior>

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:

=for comment
 "seqüências interiores" são termos desatualizado.
 Prefira "formatação codificada".

=over

=item C<IE<lt>textoE<gt>> -- texto itálico
X<I> X<< IZ<><> >> X<POD, formatando código, itálico> X<itálico>

Usado para enfatizar ("C<seja IE<lt>cuidadoso!E<gt>>") e para os parâmetros
("C<redo IE<lt>IDENTIFICADORE<gt>>")

=item C<BE<lt>textoE<gt>> -- texto em negrito
X<B> X<< BZ<><> >> X<POD, formatando código, tipo negrito> X<tipo negrito>

Usado para argumentos ("C<perl's BE<lt>-nE<gt> argumento>"), programas
("C<alguns sistemas provêem um BE<lt>chfnE<gt> para isso>"), para enfatizar
("C<seja BE<lt>cuidadoso!E<gt>>"), e assim por diante
("C<e esta característica é conhecida como BE<lt>auto-reanimaçãoE<gt>>").

=item C<CE<lt>códigoE<gt>> -- texto de código
X<C> X << CZ<><>>> X<POD, formatando código, código> X<código>

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<CE<lt>gmtime ($^T)E<gt>>") ou alguma outra
forma de I<informatiquês>("C<CE<lt> drwxr-xr-xE<gt>>").

=item C<LE<lt>nomeE<gt>>--um hiperlink
X<L> X< <LZ<><> >> X<POD, formatando código, hiperlink> X<hiperlink>

Há várias sintaxes, listadas abaixo.  Nas sintaxes dadas,
C<texto>, C<nome>, e C<seção> não pode conter os caractere
'/' e' |'; e qualquer'<' ou'> ' deveria ser encontrado.

=over

=item *

C<LE<lt>nomeE<gt>>

Referência para uma página do manual de Perl  (por exemplo, C<LE<lt>Net::PingE<gt>>).  Nota
que o C<nome> não deverá conter espaços.  Esta sintaxe
também é usado ocasionalmente para referências a UNIX I<man page>, como em
C<LE<lt>crontab (5)E<gt>>.

=item *

C<LE<lt>nome/"seção"E<gt>> ou C<LE<lt>nome/seçãoE<gt>>

Referência a uma seção em outra página do manual.  Por exemplo,
C<LE<lt>perlsyn/"For Loops"E<gt>>

=item *

C<LE<lt>/"seção"E<gt>> ou C<LE<lt>/seçãoE<gt>> ou C<LE<lt>"seção"E<gt>>

Referência uma seção nesta página manual.  Por exemplo,
C<LE<lt>/"Métodos de Objeto" "E<gt>>

=back

Uma seção é iniciada pelo comando I<head> o I<item>.  Por
exemplo, C<LE<lt>perlvar/$.E<gt>> ou C<LE<lt>perlvar/"$."E<gt>> ambos
referência à uma seção iniciada por "C<=item $.>" em perlvar.  E
C<LE<lt>perlsyn /For LoopsE<gt>> ou C<LE<lt>perlsyn/"For Loops"E<gt>>
ambos referência para a seção iniciada por "C<=head2 For Loops>"
em perlsyn.

Para controlar o texto que aparecerá, você deve utilizar
"C<LE<lt>texto|...E<gt>>", como em:

=over

=item *

C<LE<lt>texto|nomeE<gt>>

Referência este texto a uma página do manual.  Por exemplo,
C<LE<lt>Mensagens de erro de Perl|perldiagE<gt>>

=item *

C<LE<lt>texto|nome"seção"E<gt>> ou C<LE<lt>texto|nome/seçãoE<gt>>

Referência este texto à uma seção de uma página do manual.  Por exemplo,
C<LE<lt>instruções de SWITCH|perlsyn/"Básico de blocos e Instruções de Switch"E<gt>>

=item *

C<LE<lt>texto|/"seção"E<gt>> ou C<LE<lt>texto|/seçãoE<gt>>
ou C<LE<lt>texto|"seção"E<gt>>

Referência este texto a uma seção nesta página manual.  Por exemplo,
C<LE<lt>os vários atributos|/"Member Data"E<gt>>

=back

ou você pode referênciar a uma página de web:

=over

=item *

C<LE<lt>URLE<gt>>

Referência uma URL.  Por exemplo,
C<LE<lt> http://www.perl.org/E<gt>>.  Mas nota
que não há nenhuma sintaxe correspondente C<LE<lt>texto|URLE<gt>>, por
várias razões.

=back

=item C<EE<lt>escape<gt>> -- caracteres do tipo I<escape>
X<E> X<< EZ<><> >> X<POD, formatando código, escape> X<escape>


Bem parecido o HTML/XML C<&I<foo>;> "referências de entidade":

=over

=item *

C<EE<lt>ltE<gt>> -- o literal E<lt> (menos que)

=item *

C<EE<lt>gtE<gt>> -- o literal E<gt> (maior que)

=item *

C<EE<lt>verbarE<gt>> -- a literal | (barra vertical)

=item *

C<EE<lt>solE<gt>> = o literal / (delimitador de diretório)

Os quatros comandos anterios são opcionais, menos em alguns códigos de formatação,
notavelmente C<LE<lt>... E<gt>> e quando precedido por uma
letra maiúscula.

=item *

C<EE<lt>htmlnameE<gt>>

Algumas nomes de entidade HTML não-numérica, como C<EE<lt>eacuteE<gt>>,
significando a mesma coisa que C<&eacute;> em HTML--i.e., o mesmo que 'E' minúsculo
com um acento agudo.

=item *

C<EE<lt>númeroE<gt>>

O representação do caracterer em ASCII/Latin-1/Unicode do número informado. Números
iniciados com "0x" indicam que estão em I<formato númerico hexadecimal>, como 
C<EE<lt>0x201EE<gt>>.  Números iniciados com "0" indicam que estão em I<formato númerico octadecimal>,
como em C<EE<lt>075E<gt>>.  Caso contrário o I<número> será interpretado como sendo
em decimal, como em C<EE<lt>181E<gt>>.

Note que os antigos formatadores de POD podem não compreender os formatos númericos octaldecimais ou
hexadecimais, e eles podem não interpretar caracteres acima de 255.  (Algum formatters podem ter até mesmo
usar transformações baseados em caracteres Latin-1, como
C transformando em <EE<lt>eacuteE<gt>> quando na verdade o requerido é simplesmente o "e".)

=back

=item C<FE<lt>nome de arquivo<gt>> -- usado para nome de arquivos
X<F> X<<FZ<><>>>X<POD, formatando código, nomede de arquivo> X<nome de arquivo>

Tipicamente exibido em itálicos.  Exemplo: "C<FE<lt>.cshrcE<gt>>"

=item C<SE<lt>textoE<gt>> -- texto contém espaços que não podem ser quebrados
X<S> X<< SZ<><> >> X<POD, formatando código, espaços que não podem ser quebrados,> 
X<espaços que não podem ser quebrados>

Isto significa que as palavras no I<texto> não deveria ser quebrado
para a próxima linha.  Exemplo: S<C<SE<lt>$x ? $y : $ZE<gt>>>.

=item C<XE<lt>nome do tópicoE<gt>>--uma entrada de índice
X<X> X<< XZ<><> >> X<POD, formatando código, entrada de índice> X<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: C<XE<lt>absolutizing relative URLs<gt>>

=item C<oZE<lt>E<gt>> -- um código de formatação nulo (efeito zero)
X<Z> X<< ZZ<><> >> X<POD, formatando código, nulo> X<nulo>

Isto é raramente utilizado.  É algumas vezes um modo para contornar a utilização do código
EE<lt>...E<gt>.  Por exemplo, em vez de
"C<NEE<lt>ltE<gt>3>" (para "NE<lt>3") você poderia escrever
"C<NZE<lt>E<gt>E<lt>3>" (o "ZE<lt>E<gt>" quebra "N" e
o "E<lt>" assim eles não podem ser considerados
a parte de um (fictício) "NE<lt>...E<gt>" código.

=for comment
 This was formerly explained as a "zero-width character".  But it in
 most parser models, it parses to nothing at all, as opposed to parsing
 as if it were a E<zwnj> or E<zwj>, which are REAL zero-width characters.
 So "width" and "character" are exactly the wrong words.

=back

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 C<E> código:

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

Isto produzirá: "C<$a E<lt>=E<gt> $b>"

Um mais legível, e talvez modo mais "claro" é usar um substituto
conjunto de delimiters que não requer um simples">" para ser I<escaped>.  Com
o formadores de POD que é padronizado com perl5.5.660, dublos parênteses 
de ângulo ("<<" e">>") talvez possa ser utiilzado I<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:
X<POD, formatando código, escapando com parênteses de múltiplo,>

    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á:
X<POD, formatando código, escapando com parênteses de múltiplo,>

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

=head2 O objetivo
X<POD, 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 C<fmt> para reformatar-los facilmente 
(isso é F7 na minha versão do B<vi>, ou Esc Q na minha versão do B<emacs>).  

Eu queria que o tradutor sempre considerasse o C<'>, o C<`> e o
C<"> 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 B<pod2text>, B<pod2html>,
B<pod2man> (isso é para nroff (1) e troff (1)), B<pod2latex>, e
B<pod2fm>.  Vários outros estão disponíveis em CPAN.

=head2 Embute PODs em Módulos de Perl
X<POD, embutindo>

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.

=head2 Dicas para escrever POD

=over

=item *
X<podchecker> X<POD, validando>

O comando B<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.

=item *

Se você está mais familiarizado em escrever em HTML que em POD, você
pode pode escrever sua documentação em HTML simples, e convertendo-lo
para POD com o módulo experimental L<Pod::HTML2Pod|Pod::HTML2Pod>,
(disponível no CPAN), e observar o código resultante.  O módulo experimental
L<Pod::PXML|Pod::PXML> no CPAN também poderia ser útil.

=item *

Muitos tradutores de POD antigos requerem linhas antes de todo comando POD
e depois de cada comando de POD (incluindo "=cut!") ter linha com espaço em branco.
Ter algo assim:

 # - - - - - - - - - - - -
 =item $traque->estrondo()

 Este objeto detona um traque ruidoso.
 =cut
 sub estrondo {
 ...

...fará que alguns tradutores de POD falhará completamente ao ver o bloco de POD.

Ao invés, tem assim:

 # - - - - - - - - - - - -

 =item $traque->estrondo()

 Este objeto detona um traque ruidoso.

 =cut

 sub estrondo {
 ...

=item *

Alguns tradutores de POD antigos requerem parágrafos (inclusive comando de 
parágrafos como "=head2 Funciona") ser separado por linhas I<completamente>
vazias.  Se você tiver uma linha aparentemente vazia com alguns espaços
nela, isto poderia não contar como um separador para esses tradutores, e
isso poderia causar formatação estranha.

=item *

Tradutores antigos podem adicionar palavras ao redor de um LE<lt>E<gt>, desda forma
C<LE<lt>Foo::BarE<gt>> pode ser traduzido para "o manpage de Foo::Bar", por exemplo.
Assim você não deveria escrever coisas como C<o LE<lt>fooE<gt>
documentação>, se você quer o documento traduzido para facilitar a leitura
-- ao invés escreva C<o LE<lt>Foo::Bar|Foo::BarE<gt> documentação> ou
C<LE<lt> a documentação de Foo::Bar|Foo::BarE<gt>>, para controlar o vai sai.

=item *

Ultrapassando a 70ª coluna num bloco literal pode ser desagradavelmente 
embaralhado por alguns formadores.

=back

=head1 VEJA TAMBÉM

L<perlpodspec>, L<perlsyn/"PODs: Documentação embutida">,
L<perlnewmod>, L<perldoc>, L<pod2html>, L<pod2man>, L<podchecker>.

=head1 AUTOR

Larry Wall, Sean M. Burke

=cut

=head1 TRADUZINDO

Solli Moreira Honório

=cut