Pode e não pode no POD

O que pode e o que não pode ao escrever POD

Introdução

Com o Equinócio se aproximando e as submissões quase acabando, muita gente vem me perguntar como fazer esse ou aquele ajuste no seu artigo escrito com o bom e velho Plain Old Document. Então resolvi fazer uma apanhado geral sobre as principais características desse formato.

O POD é o formato de documentação padrão do Perl, no qual se escreve texto plano com algumas marcações especiais de formatação que são entendidas pelos utilitários que lidam com sua conversão e exibição. Com o perdão da licença poética, é uma espécie de HTML muito muito mais simples.

Ele foi projetado para gerar a documentação online do Perl (online aqui no sentido de disponível através da linha de comando) e embora suporte html embutido tenha sempre em mente que o POD lida melhor com texto plano.

Ele é o formato utilizado para criar documentação padrão de módulos e aplicativos, possuindo um status de elegância e classe, ou seja, se o seu código não fornece documentação em pod, então não é considerado Perl sério.

Comandos Básicos

As marcações especiais do POD começam com um sinal de =. Por exemplo, =pod, =head1, etc. Algumas ferramentas de conversão mais antiga exigem que cada comando seja separado do texto por uma linha em branco antes dele e outra depois.

Como o POD foi projetado para formatar texto, os principais comandos são de formatação de parágrafo, mas existem alguns outros para modificar o texto ou ainda embutir html. Vejamos os mais comuns:

Parágrafos e blocos

Para criar um novo parágrafo basta deixar uma linha em branco entre um texto e outro, começando o texto na primeira coluna da linha. Exemplo:

Este texto é o primeiro parágrafo.

Deixando uma linha em branco eu crio um novo parágrafo.

O exemplo anterior cria dois parágrafos quando o tradutor passar.

Para criar um bloco destacado como se fosse código fonte basta indentar o texto um nível. Por exemplo:

(Sem indentação)Este texto cria uma parágrafo comum.

(Com indentação)Já este outro, cria um bloco formatado como se fosse
código fonte.

Este aqui, cria um parágrafo normal novamente. Note que a linha imediatamente abaixo do bloco precisa ser des-indentada senão a linha abaixo dela será interpretada com parte do bloco. Exemplo:

Este aqui é um bloco

E este é um parágrafo comum, ou pelo menos deveria ser se eu não tivesse esquecido um tab na linha em branco acima. Note que dependendo da ferramenta esse erro pode ser ignorado ou não. O pod2html se perde aqui, já o formatador do github é mais esperto.

Mas se eu esquecer um espacinho sequer, aí tenho um bloco denovo.

Com um novo parágrafo, tudo volta ao normal, mas se você não souber onde procurar vai ficar louco!

Cabeçalhos

Os cabeçalhos são criados com os comandos =headN, onde o N é um número de 1 a 4. Os =headN são semelhantes aos <hN> do html.

Cada nível é aninhado dentro do anterior e o sumário no início da página é criado automaticamente baseado neles. Exemplo:

=head1 Capítulo I

=head2 Seção A

Parágrafo comum.

Outro parágrafo.

=head2 Seção B

Mais texto

=head1 Capítulo II

...

Listas

Os comandos =over, =item e back são utilizados pra criar listas de itens. Exemplo o pod abaixo:

=over

=item Item 1

=over

=item Seção A

=item Seção B

=back

=item Item 2

=over

=item Seção C

=item Seção D

=back

=back

Gera a saída:

Item 1

Seção A

Seção B

Item 2

Seção C

Seção D

Que foi corretamente interpretada pelo perldoc, pessimamente interpretada pelo pod2html e razoavelmente resolvida pelo pelo github.com.

Embutindo html

Com os comandos =begin, =end e =for é possível embutir outros formatos dentro do pod. Exemplo o pod:

=begin html

<p style="text-align: center; color: red;">Hello World!!!</p>

=end html

Parágrafor comum...

=for html
<p style="color: green;">Visite <a href="http://blabos.org/">blabos.org</a></p>

Parágrafor comum...

Resulta em:

Hello World!!!

Parágrafor comum...

Visite blabos.org

Parágrafor comum...

Novamente temos diferenças entre o que é apresentado no perldoc, no pod2html e no github.com, até porque html não é o forte do pod, dá só pra quebrar um galho.