Crea una catena di pubblicazioni con Pandoc e Docker

Oggi esamineremo più da vicino come i professionisti possono avvalersi dell'aiuto di Pandoc per creare una catena di pubblicazione solida e facile da implementare. Pandoc è uno strumento estremamente semplice ma potente che consente agli utenti di convertire documenti in vari formati, a seconda delle loro esigenze.

Può semplificare notevolmente la documentazione e la pubblicazione o persino aprire alcune nuove possibilità di automazione. Soprattutto, Pandoc si basa su Markdown compatibile con Git, il che significa che puoi anche implementare un sistema di controllo della versione per la tua documentazione senza ulteriori problemi.

A proposito di problemi, faremo affidamento su un'immagine Docker per installare Pandoc e LaTeX con un semplice pull. L'installazione del software può richiedere molto tempo e la creazione di un ambiente software funzionante da zero all'avvio di un nuovo progetto difficilmente è produttiva. Docker aiuta a mitigare questi problemi consentendo agli utenti di configurare tutto in pochi minuti, indipendentemente dalla piattaforma.

Inoltre, non è raro che i datori di lavoro richiedano di fornire l'hardware del proprio computer. Questo è spesso indicato come Bring Your Own Device (BYOD) e non dimentichiamo che la pandemia di COVID-19 ha reso il lavoro da casa molto più diffuso. Senza soluzioni come Docker, sarebbe difficile supportare applicazioni in esecuzione su hardware e sistemi operativi diversi come Windows, macOS e Linux.

Iniziamo dando un'occhiata più da vicino ai contenitori e alle immagini Docker prima di procedere con Pandoc.

Docker in soccorso

L'uso dei container Docker può eliminare la necessità di installare più applicazioni software su una nuova macchina. Le immagini Docker predefinite sono disponibili su Docker Hub per un gran numero di applicazioni. I principali fornitori di servizi cloud come AWS, Azure e Google forniscono tutti i registri dei container. Esistono molti altri registri di terze parti, inclusi GitLab e Red Hat OpenShift.

È probabile che un'immagine sarà disponibile per la maggior parte (se non tutte) le applicazioni. Ciò significa che non è necessario installare la maggior parte delle applicazioni e le relative dipendenze. L'applicazione può essere semplicemente eseguita in un contenitore Docker. Ciò elimina convenientemente i problemi associati ai membri del team che eseguono applicazioni su hardware e sistemi operativi diversi. La stessa immagine può essere utilizzata per eseguire i container su qualsiasi sistema in grado di eseguirli e gli specialisti Docker possono rendere questo processo estremamente veloce ed efficiente.

Caso d'uso Pandoc: documentazione

La documentazione può essere richiesta in diversi formati. Potrebbe essere necessario che lo stesso documento sia disponibile in formati diversi, ad esempio HTML per le presentazioni e PDF per le dispense. La conversione tra formati di file può essere noiosa e richiedere molto tempo. Una buona soluzione è avere una catena di pubblicazioni con un'unica fonte di verità. Tutti i documenti devono essere scritti nella stessa lingua. Dovrebbe essere un linguaggio basato su testo in quanto è più facile da versione e archiviare nei repository Git.

Markdown è una buona scelta per creare un'unica fonte di verità. Il software in grado di convertire i documenti Markdown in una varietà di altri formati è prontamente disponibile e tende ad essere affidabile.

Pandoc

Pandoc è un pacchetto software in grado di convertire documenti in diversi formati. In particolare, può convertire Markdown in HTML, PDF e altri formati ampiamente utilizzati. Il processo di conversione può essere personalizzato utilizzando modelli e metadati nell'origine Markdown.

Pandoc richiede un'installazione LaTeX per creare file PDF. L'installazione di Pandoc e LaTeX richiede molto tempo. Fortunatamente, esiste un'immagine Docker chiamata pandoc/latex , che elimina la necessità di installare qualcosa di diverso da Docker.

Comandi Docker

È necessario trovare o creare un'immagine Docker adatta che contenga il software necessario. È consigliabile eseguire il pull dell'immagine nel registro locale poiché il download può richiedere del tempo.

 docker pull pandoc/latex

Per eseguire un comando in un container Docker è necessario un wrapper per eseguire il container Docker ed eseguire un comando nel container. Una buona soluzione a questo è scrivere una funzione di shell su un sistema macOS o UNIX/Linux. La funzione può essere inserita in qualsiasi script di accesso o in un file separato come $HOME/.functions . È anche possibile scrivere uno script o un alias con la stessa funzionalità.

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

Questa funzione esegue le seguenti operazioni:

• Stampa il comando sullo schermo.
• Esegue un contenitore Docker pandoc/latex .
• L'opzione -it crea una sessione terminale interattiva e rende visibile l'output del comando.
• L'opzione --rm elimina il contenitore una volta terminato il comando.
• L'opzione -v $PWD:/work monta la directory corrente sull'host nella directory /work nel contenitore.
• Il -w /work rende la directory /work nel contenitore la directory di lavoro.
• Il pandoc "$@" esegue il comando pandoc nel contenitore passando tutte le opzioni della riga di comando passate alla funzione.

Una shell o uno script deve caricare la funzione in memoria.

 . $HOME/.functions

La funzione ora è un comando a sé stante e si comporta come se il binario pandoc fosse installato localmente. Questo approccio può essere utilizzato per qualsiasi comando disponibile in un'immagine Docker.

Riduci in HTML

Per convertire Markdown in HTML, è meglio utilizzare un modello e metadati in Markdown.

Metadati di riduzione

L'origine Markdown può avere una sezione di intestazione che può avere metadati arbitrari. I metadati assumono la forma di coppie chiave-valore. I valori possono essere sostituiti nel modello HTML.

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

L'intestazione inizia con una riga contenente solo tre trattini --- . È terminato con una linea contenente solo tre punti ... . Le chiavi sono singole parole seguite da due punti e dal relativo valore. Le chiavi possono essere annidate. L'esempio mostra la definizione di chiavi denominate title, links.prev e links.next .

Questo approccio utilizza un file separato per ogni pagina. Nell'esempio, la pagina precedente è index.md , la pagina corrente è page001.md e la pagina successiva è page002.md . In pratica, verrebbero utilizzati nomi di file più significativi in ​​modo che sia più facile riordinare e inserire le pagine.

Modello HTML

Un modello HTML è semplicemente un file HTML. La sostituzione dei metadati e semplici strutture di controllo possono essere aggiunte tra i simboli del dollaro. Ecco un semplice esempio di template HTML per 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>

L'esempio mostra un modello. Il $body$ viene sostituito con il testo Markdown convertito in HTML. Le istruzioni condizionali generano il collegamento HTML solo se i metadati sono definiti nell'intestazione Markdown.

Generazione HTML da Markdown

A Pandoc deve solo essere detto come vengono chiamati i file di input e output più eventuali file modello. Il formato del file di input predefinito è Markdown . Può dedurre il formato del file di output dall'estensione del file di output specificata.

I comandi per generare output possono essere uno script o un makefile.

 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

Per ogni file .md nella directory Project , crea un file .html corrispondente nella directory HTML/Project se il file di output è precedente al file di input o non esiste.

Generazione di Beamer PDF da Markdown

Beamer è un pacchetto LaTeX per la produzione di presentazioni. L'output è una presentazione in PDF.

Gli stessi file sorgente di Markdown possono essere utilizzati per generare il PDF del proiettore.

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

I dettagli del comando sono:

• L'opzione -t beamer dice di usare LaTeX e beamer per generare il PDF.
• L'opzione -o specifica il file di output.
• Le opzioni -V selezionano il tema del proiettore e il tema del colore.
• Il comando termina con un elenco di file Markdown che verranno concatenati nell'ordine indicato.

Tutta l'elaborazione viene eseguita all'interno di un container Docker.

Riduci in PDF

Anche convertire un documento Markdown in un documento PDF è abbastanza semplice. Il PDF viene sempre generato convertendo prima Markdown in LaTeX. I metadati possono essere aggiunti all'intestazione Markdown per personalizzare l'output, ad esempio per impostare il formato carta e il formato del margine.

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

Generazione PDF da Markdown

Il comando per convertire il Markdown in PDF è semplice:

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

L'opzione -s crea un documento autonomo.

Conclusione

Non è più necessario dedicare molti giorni all'installazione del software. La semplice esecuzione di un comando in un contenitore Docker elimina la necessità di installazione. Molte applicazioni hanno immagini Docker adatte su Docker Hub. Se è necessario aggiornare il software, è sufficiente estrarre l'ultima immagine Docker.

Configurare un nuovo computer è solo questione di installare Docker, estrarre le immagini necessarie e creare alcuni script.

Non è più necessario creare documenti in formati diversi. Un unico formato come Markdown può essere utilizzato per tutti i documenti. Strumenti come Pandoc possono quindi generare documenti da Markdown in un gran numero di formati diversi.

Poiché Markdown è un file di testo, una volta archiviato in un repository Git, è disponibile una cronologia completa delle versioni. I repository Git eseguono anche il rendering automatico di Markdown e consentono alle persone di commentare le modifiche senza dover utilizzare cronologie di modifiche disordinate nel file del documento stesso.