Creați un lanț de publicații cu Pandoc și Docker

Astăzi, vom arunca o privire mai atentă asupra modului în care profesioniștii pot apela la ajutorul Pandoc pentru a crea un lanț de publicații robust și ușor de implementat. Pandoc este un instrument extrem de simplu, dar puternic, care permite utilizatorilor să convertească documente în diferite formate, în funcție de cerințele lor.

Poate simplifica foarte mult documentarea și publicarea sau chiar deschide câteva posibilități noi de automatizare. Cel mai bun dintre toate, Pandoc se bazează pe Markdown prietenos cu Git, ceea ce înseamnă că puteți implementa și un sistem de control al versiunilor pentru documentația dvs. fără nicio bătaie de cap suplimentară.

Vorbind de bătăi de cap, ne vom baza pe o imagine Docker pentru a instala Pandoc și LaTeX cu o simplă tragere. Instalarea software-ului poate consuma mult timp, iar configurarea unui mediu software de lucru de la zero atunci când porniți un nou proiect este cu greu productivă. Docker ajută la atenuarea acestor probleme, permițând utilizatorilor să configureze totul în câteva minute, indiferent de platformă.

În plus, nu este neobișnuit ca angajatorii să solicite să vă furnizați propriul computer hardware. Acest lucru este adesea denumit Bring Your Own Device (BYOD) și să nu uităm că pandemia COVID-19 a făcut ca munca de acasă să fie mult mai răspândită. Fără soluții precum Docker, ar fi greu să suportați aplicații care rulează pe diverse hardware și sisteme de operare, cum ar fi Windows, macOS și Linux.

Să începem prin a arunca o privire mai atentă asupra containerelor și imaginilor Docker înainte de a trece la Pandoc.

Docker la Salvare

Utilizarea containerelor Docker poate elimina necesitatea de a instala mai multe aplicații software pe o nouă mașină. Imaginile Docker prefabricate sunt disponibile pe Docker Hub pentru un număr mare de aplicații. Furnizorii de cloud de top, cum ar fi AWS, Azure și Google, oferă toate registrele de containere. Există multe alte registre terțe, inclusiv GitLab și Red Hat OpenShift.

Este probabil ca o imagine să fie disponibilă pentru majoritatea (dacă nu pentru toate) aplicațiile. Aceasta înseamnă că nu este necesar să instalați majoritatea aplicațiilor și dependențele acestora. Aplicația poate fi pur și simplu rulată într-un container Docker. Acest lucru elimină în mod convenabil problemele asociate cu membrii echipei care rulează aplicații pe hardware diferit și sisteme de operare diferite. Aceeași imagine poate fi folosită pentru a rula containere pe orice sistem care le poate rula, iar specialiștii Docker pot face acest proces extrem de rapid și eficient.

Caz de utilizare Pandoc: documentație

Documentația poate fi necesară în mai multe formate diferite. Este posibil ca același document să fie disponibil în diferite formate, cum ar fi HTML pentru prezentări și PDF pentru fișe. Conversia între formate de fișiere poate fi plictisitoare și necesită mult timp. O soluție bună este să aveți un lanț de publicații cu o singură sursă de adevăr. Toate documentele trebuie scrise în aceeași limbă. Ar trebui să fie un limbaj bazat pe text, deoarece este mai ușor de versat și stocat în depozitele Git.

Markdown este o alegere bună pentru a crea o singură sursă de adevăr. Software-ul care poate converti documentele Markdown într-o varietate de alte formate este ușor disponibil și tinde să fie de încredere.

Pandoc

Pandoc este un pachet software care poate converti documente în diferite formate. În special, poate converti Markdown în HTML, PDF și în alte formate utilizate pe scară largă. Procesul de conversie poate fi personalizat folosind șabloane și metadate din sursa Markdown.

Pandoc necesită o instalare LaTeX pentru a crea fișiere PDF. Instalarea Pandoc și LaTeX necesită destul de mult timp. Din fericire, există o imagine Docker numită pandoc/latex , care elimină necesitatea de a instala orice altceva decât Docker.

Comenzi Docker

Trebuie găsită sau creată o imagine Docker adecvată care să conțină software-ul necesar. Este recomandabil să trageți imaginea în registrul local, deoarece descărcarea poate dura ceva timp.

 docker pull pandoc/latex

Pentru a rula o comandă într-un container Docker, este nevoie de un wrapper pentru a rula containerul Docker și a executa o comandă în container. O soluție bună pentru aceasta este să scrieți o funcție shell pe un sistem macOS sau UNIX/Linux. Funcția poate fi introdusă în orice script de conectare sau într-un fișier separat, cum ar fi $HOME/.functions . De asemenea, este posibil să scrieți un script sau un alias cu aceeași funcționalitate.

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

Această funcție face următoarele:

• Tipărește comanda pe ecran.
• Rulează un container Docker din imaginea pandoc/latex .
• Opțiunea -it creează o sesiune de terminal interactiv și face vizibilă rezultatul comenzii.
• Opțiunea --rm șterge containerul odată ce comanda sa terminat.
• Opțiunea -v $PWD:/work montează directorul curent de pe gazdă în directorul /work din container.
• -w /work face din directorul /work din container directorul de lucru.
• pandoc "$@" rulează comanda pandoc în container, trecând toate opțiunile din linia de comandă transmise funcției.

Un shell sau un script trebuie să încarce funcția în memorie.

 . $HOME/.functions

Funcția este acum o comandă de sine stătătoare și se comportă la fel ca și cum binarul pandoc a fost instalat local. Această abordare poate fi utilizată pentru orice comandă disponibilă într-o imagine Docker.

Reducere la HTML

Pentru a converti Markdown în HTML, este mai bine să utilizați un șablon și metadate în Markdown.

Metadatele Markdown

Sursa Markdown poate avea o secțiune antet care poate avea metadate arbitrare. Metadatele iau forma unor perechi cheie-valoare. Valorile pot fi înlocuite în șablonul HTML.

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

Antetul începe cu o linie care conține doar trei liniuțe --- . Se termină cu o linie care conține doar trei puncte ... . Cheile sunt cuvinte simple urmate de două puncte și valoarea acestuia. Cheile pot fi imbricate. Exemplul arată definiția cheilor numite title, links.prev și links.next .

Această abordare utilizează un fișier separat pentru fiecare pagină. În exemplu, pagina anterioară este index.md , pagina curentă este page001.md , iar pagina următoare este page002.md . În practică, ar fi folosite nume de fișiere mai semnificative, astfel încât să fie mai ușor să reordonezi și să inserezi pagini.

Șablon HTML

Un șablon HTML este pur și simplu un fișier HTML. Înlocuirea metadatelor și structurile de control simple pot fi adăugate între simbolurile dolarului. Iată un exemplu simplu de șablon HTML pentru 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>

Exemplul arată un șablon. $body$ este înlocuit cu textul Markdown convertit în HTML. Declarațiile condiționate generează linkul HTML numai dacă metadatele sunt definite în antetul Markdown.

Generarea HTML din Markdown

Pandoc trebuie doar să i se spună cum se numesc fișierele de intrare și de ieșire plus orice fișiere șablon. Formatul implicit al fișierului de intrare este Markdown . Poate deduce formatul fișierului de ieșire din extensia specificată a fișierului de ieșire.

Comenzile pentru a genera ieșiri pot fi un script sau 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

Pentru fiecare fișier .md din directorul Project , acesta creează un fișier .html corespunzător în directorul HTML/Project dacă fișierul de ieșire este mai vechi decât fișierul de intrare sau nu există.

Se generează Beamer PDF din Markdown

Beamer este un pachet LaTeX pentru producerea de prezentări. Rezultatul este o prezentare de diapozitive PDF.

Aceleași fișiere sursă Markdown pot fi folosite pentru a genera PDF beamer.

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

Detaliile comenzii sunt:

• Opțiunea -t beamer spune că utilizați LaTeX și beamer pentru a genera PDF-ul.
• Opțiunea -o specifică fișierul de ieșire.
• Opțiunile -V selectează tema beamer și tema de culoare.
• Comanda se termină cu o listă de fișiere Markdown care vor fi concatenate în ordinea dată.

Toată procesarea este efectuată în interiorul unui container Docker.

Reducere la PDF

Convertirea unui document Markdown într-un document PDF este, de asemenea, destul de simplă. PDF-ul este întotdeauna generat prin conversia mai întâi a Markdown-ului în LaTeX. Metadatele pot fi adăugate la antetul Markdown pentru a personaliza rezultatul, cum ar fi setarea dimensiunii hârtiei și a dimensiunii marginii.

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

Se generează PDF din Markdown

Comanda pentru a converti Markdown-ul în PDF este simplă:

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

Opțiunea -s creează un document independent.

Concluzie

Nu mai este necesar să petreci multe zile instalând software. Pur și simplu rularea unei comenzi într-un container Docker elimină necesitatea instalării. Multe aplicații au imagini Docker adecvate pe Docker Hub. Dacă software-ul necesită actualizare, pur și simplu trageți cea mai recentă imagine Docker.

Configurarea unui nou computer este doar o chestiune de a instala Docker, de a extrage imaginile necesare și de a crea câteva scripturi.

Nu mai este necesar să creați documente în diferite formate. Un singur format, cum ar fi Markdown, poate fi utilizat pentru toate documentele. Instrumente precum Pandoc pot genera apoi documente din Markdown într-un număr mare de formate diferite.

Deoarece Markdown este un fișier text, atunci când este verificat într-un depozit Git, este disponibil un istoric complet al versiunilor. De asemenea, arhivele Git redau automat Markdown și permit oamenilor să comenteze modificările fără a fi nevoie să folosească istoriile dezordonate ale modificărilor în fișierul document în sine.