Automatische tekstconversie met pandoc
Automatische tekstconversie met pandoc
Als je handleidingen, documentatie en brieven op een neutrale manier opmaakt, kun je daar zonder al teveel moeite een ander formaat van maken voor verschillende toepassingen. Het programma pandoc kan het converteren van teksten op zich nemen onder Windows, Linux en macOS.
Het is bij webdesigners al jaren bekend dat het geen goed idee is om content en lay-out in één en hetzelfde document te hebben staan. Die twee worden gescheiden in een contentdocument en een stylesheet, waardoor er niets aan een document meer veranderd hoeft te worden als het logo of de kleur van een kop verandert. Op kantoren is dat echter nog lang geen goede gewoonte, daar worden brieven en documenten traditioneel in Word gemaakt met briefhoofd- sjablonen en opgeslagen als DOCX. Als na een paar jaar de bedrijfsnaam of het faxnummer in een briefhoofd verandert, moeten die veranderingen omslachtig handmatig in elk sjabloon aangepast worden.
Als je ook bij dat soort documenten erop let dat je de inhoud scheidt van de lay-out, moet je daar in het begin zeker even aan wennen – net als je collega's natuurlijk. Maar daarna kun je documenten zonder problemen exporteren naar een webpagina, voor drukwerk of voor een e-bookreader.
Opmaakcodes
Documenten bestaan meestal uit een handvol elementen: teksten, afbeeldingen, tabellen, koppen en opsommingen. Om die gebruikersvriendelijk en flexibel te labelen, zijn er meerdere manieren. Het door Tim Berners Lee bedachte HTML is met zijn tags tussen < > voor teksten echter te lastig en is buiten developerskringen nooit echt populair geworden. De mark-uptaal Markdown is wezenlijk gebruiksvriendelijker. Die taal werd pas in 2004 uitgevonden. Een kop van het bovenste niveau geef je bijvoorbeeld aan met een # aan het begin van de regel. Een subkop geef je dan aan met ##. De meest gebruikte elementen staan bij de link aan het eind van dit artikel.
Markdown kun je met elke tekstverwerker gebruiken. Markdown-editors of plug-ins voor programmeeromgevingen kunnen je een eerste indruk geven van het resultaat (zie de link onderaan het artikel). De extensie is daarbij verder niet van belang, in principe volstaan .txt en .md.
Converteren
Het converteren van de Markdown-teksten naar een leesvriendelijk eindformaat wordt gedaan door de gratis commandlinetool pandoc. Bij Windows hoef je alleen de installer te downloaden en uit te voeren (zie de link onderaan). Om PDF-bestanden te maken, heeft pandoc een LaTeX-converter als MiKTeX nodig. Omdat Windows geen eigen pakketbeheer heeft, moet je die zelf installeren (zie de link onderaan).
In de pakketbronnen van de grote Linux-distributies zit meestal een oudere versie van pandoc. Bij Ubuntu kun je het samen met een LaTeX-converter bijvoorbeeld installeren met
sudo apt install pandoc sudo apt install texlive
Als je zelf een actueel pakket voor Linux wilt downloaden en compileren, staat op de
website van de ontwikkelaar een handleiding. Bij macOS moet de pakketbeheerder homebrew geïnstalleerd zijn. Het programma belandt met het commando
brew install pandoc
dan samen met alle afhankelijkheden op de Mac.
Welke versie geïnstalleerd is, kun je laten zien met het commando pandoc --version. Voor een eerste conversie heb je een klein tekstbestand test.md met voorbeeldcontent nodig zoals dit:
# Een test
* een opsomming * volgende element
Navigeer met de commandline naar de folder waar het bestand in staat en laat pandoc er daar een HTML-bestand van maken:
pandoc test.md -o test.html
De parameter -o zorgt ervoor dat het resultaat weggeschreven wordt naar het bestand test.html. Pandoc herkent aan de bestandsextensie welk exportformaat zinvol is. Het resultaat is een stukje HTML:
<h1 id="een-test">Een test</h1> <ul>
<li>een opsomming</li> <li>volgend element</li>
</ul>
HTML-commentaren, ingeleid met <!-- en afgesloten met -->, worden door pandoc bij documenten omgezet naar onzichtbare commentaren. Als je ze helemaal wilt verwijderen, voeg je de parameter --stripcomments toe bij het aanroepen van het programma. In plaats van een Markdownbestand kun je ook andere invoerformaten testen: pandoc doet het ook goed bij het inlezen van Word-bestanden (als de layoutmogelijkheden van Word tenminste niet al teveel misbruikt zijn). Ook webpagina's kunnen worden ingelezen en de content eruit gehaald. Typ bij het aanroepen van het programma dan simpelweg een url met https:// in plaats van een bestandsnaam.
Op dit moment levert pandoc alleen nog fragmenten van een webpagina op. Om een volledige HTML-structuur met <head> en <body> te genereren, is er de parameter -s (voor standalone). Als je naar de broncode van een op die manier gemaakte webpagina kijkt, zul je elementen zien die je niet zelf gedefinieerd hebt. Die komen van de standaard-template die pandoc voor HTML gebruikt. Je kunt heel makkelijk zelf HTML-templates maken. Maak het bestand html_temp.html aan in dezelfde folder als het Markdown-bestand:
<html>
<head> <title>$title$</title> </head>
<body>
<h1>$title$</h1>
$body$ <footer>$copy$</footer> </body>
</html>
Om die template te gebruiken, voeg je de parameter --template=html_temp.html toe aan het pandoc-commando. De variabele $body$ wordt door pandoc automatisch vervangen door de geconverteerde inhoud van het bronbestand. Daarbij doet pandoc een poging om $title$ en $copy$ uit een metablok te halen, dat je aan het begin van een bestand in YAML-formaat tussen -- en … kunt zetten.
-title: testdocument author:
- auteur 1
- auteur 2 copy:geen copyright ... Binnen die meta-informatie kun je je helemaal uitleven en complexere templates met meerdere variabelen maken. Als een element in een later document alleen getoond moet worden als de variabele in het YAML-blok gedefinieerd is, kun je dat in het templatebestand met if-commando's oplossen:
$if(author)$
<ul>
$for(author)$
<li>$author$</li> $endfor$
</ul>
$endif$
Als de variabele author gedefinieerd is, krijgt het gegenereerde document een ongeordende lijst met een item voor elke auteursnaam. Bij het werken met lange documenten die uit hoofdstukken bestaan (werkstukken of uitgebreide handleidingen), is een inhoudsopgave wel handig. Die kan door pandoc automatisch gegenereerd worden op basis van de koppen en een hiërarchie weergeven van de verschillende kopniveaus. In een template kun je de positie van de inhoudsopgave met de volgende regels instellen:
$if(toc)$ $toc$ $endif$
Bij het aanroepen van pandoc leidt de
parameter --toc ertoe dat er een inhoudsopgave geproduceerd wordt. Met de extra toevoeging --toc-depth= geef je aan tot welk niveau de koppen getoond moeten worden. Zonder die parameter loopt dat tot het derde niveau (###). Als je de afzonderlijke hoofdstukken in aparte bestanden hebt staan, kun je bij het exporteren meerdere Markdown-bestanden opgeven. Zet de bestandsnamen in de juiste volgorde bij het aanroepen van het programma, dan zorgt pandoc ervoor dat alles op de juiste manier gecombineerd wordt:
pandoc -s hoofdstuk1.md hoofdstuk2.md
-o paper.htm
Briefhulp
Bij een zakelijke brief, die in een vensterenveloppe moet worden verstuurd, is het belangrijk dat het adresveld op de juiste positie staat. Als je de briefschrijver zijn brief in Markdown laat opstellen, dan kan pandoc het juist positioneren voor zijn rekening nemen. Met een beetje CSS ontstaat een makkelijk aan te passen sjabloon voor zakelijke brieven volgens DIN 5008 als HTML. Bij de link onderaan deze pagina staat een kant-en-klaar template-bestand dat alle elementen met behulp van CSS op de goede plek zet en automatisch rekening houdt met de gangbare papiermarges. Daar staat ook een markdown-sjabloonbestand voor een zakelijke brief. Die gebruik je met het volgende commando:
pancod brondocument.md -o brief.html --template=template_brief.htm
--metadata date='%date%' Om zo'n brief niet handmatig te hoeven dateren, gebruik je de interne datumfunctie van het besturingssysteem en geef je de datum door aan pandoc. Bij Windows gaat dat met PowerShell met date="$(date -Format d.MM.yyyy)", bij Linux en macOS krijg je met date +'%d.%m.%Y' de datum in Europees formaat.
Het proces
Tot nu toe moest het converteren nog handmatig gestart worden, maar het zou natuurlijk praktischer zijn om een map 'incoming' aan te maken waarin je alleen het ruwe bestand van je brief hoeft te zetten om een kant-en-klaar geformatteerde brief te krijgen. Afhankelijk van het besturingssysteem moet je een andere manier gebruiken om pandoc van de juiste parameters te voorzien.
Bij Windows kun je aan de gang met de PowerShell en de klasse System.IO. FileSystemWatcher. In het kader onderaan op de vorige pagina staat het bijbehorende script. Je kunt het ook downloaden via de link onderaan dit artikel. Het script gaat er vanuit dat het in een map staat waarin de drie submappen 'templates', 'incoming' en 'output' staan. Het script reageert alleen op .md-bestanden met de extensie .md. Om ervoor te zorgen dat het programma blijft draaien, kun je er bij Windows een geplande taak van maken die het automatisch start elke keer als de computer opstart.
Bij Linux heb je het programma incron nodig, dat toegang tot folders bewaakt en reageert door een programma te starten. Het lijkt qua opbouw op de Linux-klassieker cron, die zorgt voor taken die op tijd aangestuurd moeten worden. Installeer incron met
sudo apt install incron
De regels bewerk je met incrontab -e. Om alle brieven te converteren die in /home/ joe/post/incoming gezet worden, voeg je de volgende regel toe:
/home/joe/post/incoming IN_MOVED_TO
pandoc -o /home/joe/post/out/$#.html
Met $# geeft incron de bestandsnaam van het bronbestand door aan pandoc. Sla het incrontab-bestand op en zet een brief in de map incoming. Een paar seconden later staat er een geconverteerd bestand in de folder out.
Bij macOS heb je de mogelijkheid om folderacties in te stellen en er met Apples scripttaal AppleScript voor te zorgen dat pandoc start. Die taal is zo ontworpen dat hij voor mensen makkelijk te lezen is – daardoor wordt zelfs een simpele taak echter heel lang. Het script hebben we bij de link hieronder gezet. Download het en zet het in de folder /Library/Scripts/Folder Action Scripts/, zodat macOS er toegang toe heeft. Klik op de te bewaken folder en kies in het menu 'Finder / Voorzieningen / Mapacties-configuratie'. In de dialoog kun je met een klik op het plusteken de actie toevoegen. Activeer de folderactie bovendien linksboven.
Conclusie
Het werken met pandoc loont met name als je regelmatig terugkerende taken moet uitvoeren. Systeembeheerders kunnen bijvoorbeeld een bedrijfsbrede omgeving ter beschikking stellen om brieven te produceren. De medewerkers zetten hun Markdown-teksten op een netwerkschijf, het resultaat wordt automatisch geprint en op de postafdeling ingepakt. Tegelijkertijd wordt een kopie van de tekst in het archief gezet.
Ook voor wetenschappelijk werk is het programma – zeker in combinatie met Markdown – een zinvol alternatief voor het rechtstreeks schrijven van LaTeX-documenten met hun minder gebruiksvriendelijke syntaxis. Op internet staan veel sjablonen. De ontwikkelaars hebben ook gedacht aan ondersteuning voor gangbare bibliografieformaten en het genereren van wiskundige formules. Als je e-books voor verschillende readers moet produceren, zijn er eveneens verschillende handleidingen over hoe je dat met pandoc kunt doen. (nkr)