Crear una cadena de publicaciones con Pandoc y Docker

Hoy, analizaremos más de cerca cómo los profesionales pueden obtener la ayuda de Pandoc para crear una cadena de publicación sólida y fácil de implementar. Pandoc es una herramienta extremadamente simple pero poderosa que permite a los usuarios convertir documentos en varios formatos, según sus requisitos.

Puede simplificar enormemente la documentación y la publicación, o incluso abrir algunas nuevas posibilidades de automatización. Lo mejor de todo es que Pandoc se basa en Markdown compatible con Git, lo que significa que también puede implementar un sistema de control de versiones para su documentación sin ningún problema adicional.

Hablando de molestias, confiaremos en una imagen de Docker para instalar Pandoc y LaTeX con un simple tirón. La instalación de software puede llevar mucho tiempo, y configurar un entorno de software funcional desde cero al iniciar un nuevo proyecto es poco productivo. Docker ayuda a mitigar estos problemas al permitir que los usuarios configuren todo en minutos, independientemente de la plataforma.

Además, no es raro que los empleadores le exijan que proporcione su propio hardware de computadora. Esto a menudo se conoce como Traiga su propio dispositivo (BYOD), y no olvidemos que la pandemia de COVID-19 ha hecho que trabajar desde casa sea mucho más frecuente. Sin soluciones como Docker, sería difícil admitir aplicaciones que se ejecutan en hardware y sistemas operativos diversos, como Windows, macOS y Linux.

Empecemos por echar un vistazo más de cerca a los contenedores e imágenes de Docker antes de pasar a Pandoc.

Docker al rescate

El uso de contenedores Docker puede eliminar la necesidad de instalar varias aplicaciones de software en una máquina nueva. Las imágenes de Docker prediseñadas están disponibles en Docker Hub para una gran cantidad de aplicaciones. Los principales proveedores de la nube, como AWS, Azure y Google, proporcionan registros de contenedores. Hay muchos otros registros de terceros, incluidos GitLab y Red Hat OpenShift.

Es probable que una imagen esté disponible para la mayoría de las aplicaciones (si no para todas). Esto significa que no es necesario instalar la mayoría de las aplicaciones y sus dependencias. La aplicación se puede ejecutar simplemente en un contenedor Docker. Esto elimina convenientemente los problemas asociados con los miembros del equipo que ejecutan aplicaciones en diferentes hardware y diferentes sistemas operativos. La misma imagen se puede usar para ejecutar contenedores en cualquier sistema que pueda ejecutarlos, y los especialistas de Docker pueden hacer que este proceso sea extremadamente rápido y eficiente.

Caso de uso de Pandoc: Documentación

Es posible que se requiera documentación en varios formatos diferentes. Es posible que el mismo documento deba estar disponible en diferentes formatos, como HTML para presentaciones y PDF para folletos. La conversión entre formatos de archivo puede ser tediosa y requerir mucho tiempo. Una buena solución es tener una cadena de publicaciones con una única fuente de verdad. Todos los documentos deben estar escritos en el mismo idioma. Debería ser un lenguaje basado en texto, ya que es más fácil de versionar y almacenar en los repositorios de Git.

Markdown es una buena opción para crear una única fuente de verdad. El software que puede convertir documentos de Markdown en una variedad de otros formatos está fácilmente disponible y tiende a ser confiable.

Pandoc

Pandoc es un paquete de software que puede convertir documentos en diferentes formatos. En particular, puede convertir Markdown a HTML, PDF y otros formatos ampliamente utilizados. El proceso de conversión se puede personalizar usando plantillas y metadatos en la fuente de Markdown.

Pandoc requiere una instalación de LaTeX para crear archivos PDF. La instalación de Pandoc y LaTeX lleva bastante tiempo. Afortunadamente, hay una imagen de Docker llamada pandoc/latex , que elimina la necesidad de instalar cualquier otra cosa que no sea Docker.

Comandos acoplables

Es necesario encontrar o crear una imagen de Docker adecuada que contenga el software necesario. Es recomendable extraer la imagen al registro local, ya que la descarga puede demorar algún tiempo.

 docker pull pandoc/latex

Para ejecutar un comando en un contenedor Docker, se requiere un contenedor para ejecutar el contenedor Docker y ejecutar un comando en el contenedor. Una buena solución para esto es escribir una función de shell en un sistema macOS o UNIX/Linux. La función se puede colocar en cualquier secuencia de comandos de inicio de sesión o en un archivo separado, como $HOME/.functions . También es posible escribir un script o un alias con la misma funcionalidad.

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

Esta función hace lo siguiente:

• Imprime el comando en la pantalla.
• Ejecuta un contenedor Docker desde la imagen pandoc/latex .
• La opción -it crea una sesión de terminal interactiva y hace visible la salida del comando.
• La opción --rm elimina el contenedor una vez que finaliza el comando.
• La opción -v $PWD:/work monta el directorio actual en el host en el directorio /work en el contenedor.
• El -w /work hace que el directorio /work en el contenedor sea el directorio de trabajo.
• El pandoc "$@" ejecuta el comando pandoc en el contenedor pasando todas las opciones de la línea de comandos pasadas a la función.

Un shell o un script necesita cargar la función en la memoria.

 . $HOME/.functions

La función ahora es un comando por derecho propio y se comporta de la misma manera que si el binario pandoc estuviera instalado localmente. Este enfoque se puede usar para cualquier comando disponible en una imagen de Docker.

Rebaja a HTML

Para convertir Markdown a HTML, es mejor usar una plantilla y metadatos en Markdown.

Metadatos de rebajas

La fuente de Markdown puede tener una sección de encabezado que puede tener metadatos arbitrarios. Los metadatos adoptan la forma de pares clave-valor. Los valores se pueden sustituir en la plantilla HTML.

 --- title: Document title links: prev: index next: page002 ...

El encabezado comienza con una línea que contiene solo tres guiones --- . Se termina con una línea que contiene sólo tres puntos ... . Las claves son palabras sueltas seguidas de dos puntos y su valor. Las claves se pueden anidar. El ejemplo muestra la definición de claves llamadas title, links.prev y links.next .

Este enfoque utiliza un archivo separado para cada página. En el ejemplo, la página anterior es index.md , la página actual es page001.md y la página siguiente es page002.md . En la práctica, se usarían nombres de archivo más significativos para que sea más fácil reordenar e insertar páginas.

Plantilla HTML

Una plantilla HTML es simplemente un archivo HTML. Se pueden agregar estructuras de control simple y sustitución de metadatos entre símbolos de dólar. Aquí hay un ejemplo simple de una plantilla HTML para Pandoc:

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

El ejemplo muestra una plantilla. El $body$ se reemplaza con el texto Markdown convertido a HTML. Las declaraciones condicionales solo generan el enlace HTML si los metadatos están definidos en el encabezado Markdown.

Generando HTML desde Markdown

Pandoc solo necesita que le digan cómo se llaman los archivos de entrada y salida, además de los archivos de plantilla. El formato de archivo de entrada predeterminado es Markdown . Puede inferir el formato del archivo de salida a partir de la extensión del archivo de salida especificado.

Los comandos para generar resultados pueden ser un script o un archivo MAKE.

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

Para cada archivo .md en el directorio del Project , crea un archivo .html correspondiente en el directorio HTML/Project si el archivo de salida es más antiguo que el archivo de entrada o no existe.

Generación de Beamer PDF desde Markdown

Beamer es un paquete LaTeX para producir presentaciones. El resultado es una presentación de diapositivas en PDF.

Los mismos archivos de origen de Markdown se pueden usar para generar el PDF del proyector.

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

Los detalles del comando son:

• La opción -t beamer dice usar LaTeX y beamer para generar el PDF.
• La opción -o especifica el archivo de salida.
• Las opciones -V seleccionan el tema del proyector y el tema de color.
• El comando finaliza con una lista de archivos Markdown que se concatenarán en el orden indicado.

Todo el procesamiento se realiza dentro de un contenedor Docker.

Rebaja a PDF

Convertir un documento Markdown en un documento PDF también es bastante simple. El PDF siempre se genera convirtiendo primero Markdown a LaTeX. Se pueden agregar metadatos al encabezado Markdown para personalizar la salida, como configurar el tamaño del papel y el tamaño del margen.

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

Generación de PDF desde Markdown

El comando para convertir Markdown a PDF es simple:

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

La opción -s crea un documento independiente.

Conclusión

Ya no es necesario pasar muchos días instalando software. Simplemente ejecutar un comando en un contenedor Docker elimina la necesidad de instalación. Muchas aplicaciones tienen imágenes de Docker adecuadas en Docker Hub. Si el software necesita una actualización, simplemente extraiga la última imagen de Docker.

Configurar una nueva computadora es solo una cuestión de instalar Docker, extraer las imágenes necesarias y crear algunos scripts.

Ya no es necesario crear documentos en diferentes formatos. Se puede utilizar un único formato, como Markdown, para todos los documentos. Herramientas como Pandoc pueden generar documentos desde Markdown en una gran cantidad de formatos diferentes.

Como Markdown es un archivo de texto, cuando se registra en un repositorio de Git, está disponible un historial completo de versiones. Los repositorios de Git también procesan automáticamente Markdown y permiten que las personas comenten los cambios sin tener que usar historiales de cambios desordenados en el archivo del documento.