Converter POD para PDF

Um leitor, fluxo de trabalho de impressão ou sistema de gerenciamento de documentos pode exigir PDF em vez do formato-fonte POD do Perl. Converter POD para HTML primeiro preserva títulos, listas, exemplos de código e links de forma mais confiável do que tratar a fonte como texto simples.

O que é o formato POD

POD significa Plain Old Documentation, a linguagem de marcação leve do Perl para documentar programas e módulos. Ela aparece comumente em arquivos .pod independentes e dentro de arquivos .pm ou .pl. Diretivas como =head1, =over, =item e =cut definem títulos, listas e o limite entre a documentação e o código Perl.

Distribuições do Perl, pacotes do CPAN, repositórios de código-fonte do Perl, fluxos de trabalho de fontes de manuais Unix e arquivos de documentação de desenvolvedores usam POD. Um arquivo POD é uma marcação-fonte, e não um documento de layout de página, portanto sua aparência final depende do renderizador.

O que é o formato PDF

PDF é um formato de documento orientado a páginas que pode preservar paginação, fontes, imagens, links, metadados e configurações de impressão entre sistemas operacionais. Ele é adequado para impressão, anexos de e-mail, cópias arquivadas, sistemas de gerenciamento de documentos e dispositivos sem Perl ou um renderizador de POD.

PDF é mais difícil de editar estruturalmente do que POD. Mantenha o arquivo .pod, .pm ou .pl original como fonte editável depois de criar o PDF.

Como converter POD para PDF localmente

Gerar HTML com pod2html

1. Instale o Perl. Linux e macOS geralmente já o incluem; no Windows, o Strawberry Perl fornece o Perl e os utilitários POD padrão.
2. Abra um terminal no diretório que contém o arquivo-fonte e execute:

pod2html --outfile=manual.html manual.pod

O mesmo comando pode ler um módulo ou script Perl que contenha POD:

pod2html --outfile=manual.html Module.pm

Somente a documentação POD é renderizada; o código Perl fora das seções POD não é executado nem convertido em código-fonte formatado.

Imprimir o HTML como PDF

1. Abra manual.html no Chrome, Chromium, Microsoft Edge ou Firefox.
2. Escolha Print, selecione Salvar como PDF ou Microsoft Print to PDF, escolha o tamanho do papel e as margens e salve a saída como manual.pdf.
3. Ative os gráficos de fundo somente quando a folha de estilos usar fundos. Revise cabeçalhos, rodapés, quebras de página, links, recuo do código e a contagem final de páginas.

Automatizar a saída de PDF do navegador

Chrome ou Chromium podem criar o PDF sem abrir uma caixa de diálogo de impressão:

chromium --headless --disable-gpu --print-to-pdf=manual.pdf file:///absolute/path/manual.html

Substitua chromium por google-chrome ou pelo nome do executável instalado no sistema. Use uma URL file:// absoluta; caminhos relativos podem falhar em comandos de navegador headless.

Controlar o layout com CSS

Para títulos, blocos de código e margens de página, forneça uma folha de estilos ao gerar o HTML:

pod2html --css=manual.css --title="Manual" --outfile=manual.html manual.pod

O CSS de impressão pode definir margens de página e reduzir quebras inadequadas de blocos de código:

@page { margin: 20mm; } pre { break-inside: avoid; }

As configurações de impressão do navegador ainda controlam o tamanho do papel, cabeçalhos, rodapés, escala e renderização do plano de fundo. Uma folha de estilos local ou imagem referenciada por um caminho relativo deve continuar disponível quando o HTML for aberto.

Opções de conversão online

O suporte direto de .pod para PDF é incomum porque a extensão .pod pode identificar tipos de arquivo não relacionados, e muitos serviços de conversão não incluem um analisador de Perl POD. Para um arquivo não confidencial, gere manual.html localmente com pod2html e, em seguida, envie o HTML para um serviço confiável de conversão de HTML para PDF, como o CloudConvert, se a conversão local pelo navegador não estiver disponível.

Confirme se o serviço aceita HTML e preserva CSS vinculado, imagens, Unicode e hiperlinks antes de confiar na saída. Não envie código-fonte proprietário ou documentação privada, a menos que os termos de retenção, transferência e exclusão do provedor sejam aceitáveis; remova os arquivos enviados depois da conversão quando o serviço permitir.

Verificações de qualidade e compatibilidade

pod2html interpreta a semântica do POD, mas não reproduz exatamente a saída do terminal, a formatação de páginas de manual Unix ou os estilos personalizados de renderizadores Perl. Diretivas de formatação não compatíveis podem ser ignoradas, e links para arquivos locais, módulos instalados ou páginas de manual geradas podem não funcionar no PDF.

Inspecione listas aninhadas, recuo de código literal, caracteres de escape, símbolos Unicode, hiperlinks, tabelas, imagens e quebras de página. Caixas vazias geralmente indicam um glifo ausente; use uma fonte compatível com Unicode no navegador ou no CSS. Blocos de código muito longos ainda podem ser divididos entre páginas apesar de break-inside: avoid, porque os navegadores nem sempre conseguem manter um bloco grande em uma única página.