Convertir POD a PDF

Un lector, flujo de trabajo de impresión o sistema de gestión de documentos puede requerir PDF en lugar del formato de código fuente POD de Perl. Convertir POD a HTML primero conserva los encabezados, las listas, los ejemplos de código y los enlaces de forma más fiable que tratar el código fuente como texto sin formato.

Qué es el formato POD

POD significa Plain Old Documentation, el lenguaje de marcado ligero de Perl para documentar programas y módulos. Suele aparecer en archivos independientes .pod y dentro de archivos .pm o .pl. Directivas como =head1, =over, =item y =cut definen encabezados, listas y el límite entre la documentación y el código de Perl.

Las distribuciones de Perl, los paquetes de CPAN, los repositorios de código fuente de Perl, los flujos de trabajo de código fuente de manuales de Unix y los archivos de documentación para desarrolladores utilizan POD. Un archivo POD es código fuente de marcado, no un documento con diseño de página, por lo que su apariencia final depende del renderizador.

Qué es el formato PDF

PDF es un formato de documento orientado a páginas que puede conservar la paginación, las fuentes, las imágenes, los enlaces, los metadatos y la configuración de impresión en distintos sistemas operativos. Es adecuado para imprimir, enviar como archivo adjunto por correo electrónico, crear copias de archivo, utilizarlo en sistemas de gestión de documentos y emplearlo en dispositivos que no tienen Perl ni un renderizador de POD.

PDF es más difícil de editar estructuralmente que POD. Conserva el archivo original .pod, .pm o .pl como código fuente editable después de crear el PDF.

Cómo convertir POD a PDF localmente

Generar HTML con pod2html

1. Instala Perl. Linux y macOS suelen incluirlo; en Windows, Strawberry Perl proporciona Perl y las utilidades estándar de POD.
2. Abre un terminal en el directorio que contiene el archivo de código fuente y ejecuta:

pod2html --outfile=manual.html manual.pod

El mismo comando puede leer un módulo o script de Perl que contenga POD:

pod2html --outfile=manual.html Module.pm

Solo se renderiza la documentación POD; el código de Perl fuera de las secciones POD no se ejecuta ni se convierte en código fuente con formato.

Imprimir el HTML como PDF

1. Abre manual.html en Chrome, Chromium, Microsoft Edge o Firefox.
2. Elige Print, selecciona Guardar como PDF o Microsoft Print to PDF, elige el tamaño del papel y los márgenes, y guarda el resultado como manual.pdf.
3. Activa los gráficos de fondo solo cuando la hoja de estilos utilice fondos. Revisa los encabezados, pies de página, saltos de página, enlaces, sangría del código y el número final de páginas.

Automatizar la salida PDF del navegador

Chrome o Chromium pueden crear el PDF sin abrir un cuadro de diálogo de impresión:

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

Sustituye chromium por google-chrome o por el nombre del ejecutable instalado en el sistema. Utiliza una URL absoluta file://; las rutas relativas pueden fallar en los comandos del navegador en modo headless.

Controlar el diseño con CSS

Para los encabezados, los bloques de código y los márgenes de página, proporciona una hoja de estilos al generar el HTML:

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

El CSS de impresión puede definir los márgenes de página y reducir las divisiones poco adecuadas de los bloques de código:

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

La configuración de impresión del navegador sigue controlando el tamaño del papel, los encabezados, los pies de página, la escala y el renderizado del fondo. Una hoja de estilos o imagen local a la que se haga referencia mediante una ruta relativa debe seguir disponible cuando se abra el HTML.

Opciones de conversión en línea

La compatibilidad directa de .pod a PDF es poco común porque la extensión .pod puede identificar tipos de archivos no relacionados y muchos servicios de conversión no incluyen un analizador de Perl POD. Para un archivo no confidencial, genera manual.html localmente con pod2html y, a continuación, envía el HTML a un servicio acreditado de conversión de HTML a PDF, como CloudConvert, si la conversión local mediante el navegador no está disponible.

Confirma que el servicio acepte HTML y conserve el CSS enlazado, las imágenes, Unicode y los hipervínculos antes de confiar en su resultado. No subas código fuente propietario ni documentación privada a menos que las condiciones de conservación, transferencia y eliminación del proveedor sean aceptables; elimina los archivos subidos después de la conversión cuando el servicio lo permita.

Comprobaciones de calidad y compatibilidad

pod2html interpreta la semántica de POD, pero no reproduce exactamente la salida del terminal, el formato de las páginas de manual de Unix ni los estilos personalizados de los renderizadores de Perl. Es posible que se ignoren las directivas de formato no compatibles y que los enlaces a archivos locales, módulos instalados o páginas de manual generadas no funcionen en el PDF.

Inspecciona las listas anidadas, la sangría del código literal, los caracteres escapados, los símbolos Unicode, los hipervínculos, las tablas, las imágenes y los saltos de página. Los cuadros vacíos suelen indicar que falta un glifo; utiliza una fuente compatible con Unicode en el navegador o en CSS. Los bloques de código muy largos aún pueden dividirse entre páginas a pesar de break-inside: avoid, porque los navegadores no siempre pueden mantener un bloque que supera el tamaño de una página en una sola página.